Table of Contents
Help to the folks keeping an ACS installation up and running.
Help to the folks keeping an OpenACS installation up and running.
+Table of Contents
+ +Table of Contents
This is the place to look if you want to extend the ACS and build on top -of what's already here. Here you can find out about the guts of the system.
This is the place to look if you want to extend OpenACS and build on top + of what's already here. Here you can find out about the guts of the system.
+Table of Contents
+Table of Contents
You will need a special user account for running the ACS. We recommend - that you call this user nsadmin. This user will have a - special home directory for storing AOLserver, - /home/aol31 and a special group for the server files, - web as well. You will also need to create directories - for AOLserver, /usr/local/aolserver, and for web - services, /web to reside in. You must execute this step - as root.
- Open up a terminal and run these commands:
Install AOLserver 3.3+ad13 + + + + + + + + + ++ ++ +++ Mat Kovach is graciously maintaining an AOLServer distribution that + includes all the patches and modules needed to run OpenACS 4. These + instructions will describe how to install using his source + distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and + perhaps more to come), currently located at uptime.openacs.org. +
++ It's also possible to download all the pieces and patches yourself: +
+++
- +
+ AOLServer is available at aolserver.com +
- +
+ ArsDigita's AOLServer distribution (including + internationalization patches, nscache, nsrewrite, nssha1 and the + oracle driver) is available at arsdigita.com +
- +
+ The OpenACS PostgreSQL driver is available from OpenACS +
- +
+ nsxml is available at http://acs-misc.sourceforge.net. +
- +
+ The patch that makes exec work + on BSD is available at sourceforge.net +
- +
+ The patch that makes ns_uuencode + work for binary files is available at sourceforge.net +
- +
+ The patch that makes AOLServer respect the + -g flag is available at sourceforge.net +
+ + .... or just Download Mat's + AOLServer distribution to + /tmp + +
++joeuser:~$ cd /tmp +joeuser:/tmp$ wget -c http://uptime.openacs.org/aolserver-openacs/aolserver3.3ad13-oacs1-beta-src.tar.gz +joeuser:/tmp$ cd++ + As root, untar + aolserver3.3ad13-oacs1-beta-src.tar.gz + into /usr/local/src + +
++joeuser:~$ su - +Password: ********** +root:~$ cd /usr/local/src +root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz++ ++ You will need a special user account for running AOLServer. This user + will be called nsadmin and belong + top the special group web. + nsadmin's home directory will + be /usr/local/aolserver.You must + execute these steps as root. +
+
- +
+ Run these commands: +
++root:/usr/local/src# cd +root:~# groupadd nsadmin +root:~# groupadd web +root:~# useradd -g nsadmin -G web -d /usr/local/aolserver nsadmin +root:~# passwd nsadmin ; Set password for nsadmin -# mkdir /web -# mkdir /usr/local/aolserver -# chown nsadmin.web /home/aol31 -# chown nsadmin.web /web -# chown nsadmin.web /usr/local/aolserver -# chmod 775 /home/aol31 -# chmod 775 /web -# chmod 775 /usr/local/aolserver - -# exit - -
- At this point, you should customize the nsadmin - login scripts. Login as nsadmin and add the - following lines to your ~nsadmin/.bash_profile
- +
At this point, you should customize the + nsadmin login scripts. Login as + nsadmin and add the following + lines to your + /usr/local/aolserver/.bash_profile: +
++joeuser:~$ su - nsadmin +Password: *********** +nsadmin:~$ emacs .bash_profile++ Add the first set of lines, if you're using Oracle. The 2nd set + of lines, if you're using PostgreSQL. Oracle + Note: These environment variables are specific for a + local Oracle installation communicating via IPC. If you are + connecting to a remote Oracle installation, you'll need to adjust + these appropriately. Also, make sure that the '8.1.7' matches + your Oracle version. +
++# For Oracle export ORACLE_BASE=/ora8/m01/app/oracle -export ORACLE_HOME=$ORACLE_BASE/product/8.1.6 +export ORACLE_HOME=$ORACLE_BASE/product/8.1.7 export PATH=$PATH:$ORACLE_HOME/bin export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib export ORACLE_SID=ora8 export ORACLE_TERM=vt100 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data -
Be absolutely certain that you have entered these lines correctly - and that you have saved the file - a slight error in these lines can - lead to many inscrutable error messages. Logout and log back in so - these settings will take effect.
Login as nsadmin and save files to the - /tmp directory.
- Download the AOLserver distribution and the Oracle driver (needed for - db connectivity and the ACS). You must download the source - distribution of AOLserver in order to compile the Oracle driver.
AOLserver 3.1 - Source Distribution
- Do not download a binary!
We recommend saving these archives in the /tmp - directory on your server.
- Uncompress the downloaded components; you may need to substitute - different files names and account for directory names different from - the ones below -- these were the files as of 9/2000 :
-$ cd /tmp {or wherever the archives are} -$ tar -xzf aolserver-src-3.1ad8.tar.gz -$ tar -xzf oracle-driver-2.3.tar.gz - -
- You should now have two directory trees in the current directory: - aolserver/ and oracle-driver-2.3/. - Move the oracle directory under the aolserver directory to make - compiling the Oracle driver easier:
This step should be completed as the nsadmin user. You will compile - the AOLserver distribution and prepare for installation.
Now you need to compile the Oracle driver to enable database - connectivity.
- Change directories to the - aolserver/oracle-driver-2.3 directory and start the - compilation:
The following compiler warning may be ignored:
If the compilation failed, make sure the environment variables - above actually point to where you installed the AOLserver source - code. If you followed our instructions, this should not be a problem. - You can check the directories by doing:
If you don't see any files, then you have the wrong - directories. Verify your installation of Oracle and AOLserver and try - again.
If compilation was successful, you should now have two new files - in /tmp/aolserver/oracle-driver-2.3, ora8.so and - ora8cass.so.
You are now ready to install AOLserver.
- Change directories to your AOLserver source distribution and run - make install to install the files:
- The above will copy the compiled AOLserver files to - /usr/local/aolserver -
- You should now have a /usr/local/aolserver/bin - directory. Copy the previously compiled Oracle drivers into it:
- The latest version of the ArsDigita Community System requires Tcl - 8.3. Although this version of Tcl is included with AOLserver 3.1, it - is not activated by default. There is a symbolic link pointing from - nsd to nsd76 in - /tmp/aolserver/bin. Change this to point to - nsd8x:
- You will now test to ensure AOLserver is running correctly. You - should be able to cd into your aolserver directory and simply start - the server:
As the AOLserver daemon starts up, you should see a few normal - warnings (listed below), which are safe to ignore. The first warning - means that the server is missing files for running - ssl, a necessary module for encrypted HTTPS. The - second warning means that the AOLserver control panel, a special - module for administering AOLserver, could not be loaded. If - you're interested in configuring and using either of these - modules, please see the AOLserver - documentation.
+ Be absolutely certain that you have entered these lines correctly + and that you have saved the file - a slight error in these lines + can lead to many inscrutable error messages. Logout and log back + in so these settings will take effect. Use the + echo command to be sure that the + environment variables have been properly assigned. +
++nsadmin:~$ exit +joeuser:~$ su - nsadmin +Password: ********* +nsadmin:~$ echo $PATH +...some other directory paths...:/usr/local/pgsql/bin +nsadmin:~$ echo $LD_LIBRARY_PATH +:/usr/local/pgsql/lib++ Note: The result should be different if you're using Oracle. + /ora8/m01/app/oracle/product/8.1.7 + should have been in $PATH. +
+ + ++ +++ + In order for nsxml to compile, you need libxml2 + (available from http://xmlsoft.org). On Debian, + this can be installed by doing apt-get install + libxml2-dev. Users of other distributions can + download rpms from ftp.gnome.org. You'll + need the libxml2 and + libxml2-devel packages. +
++ ++++
- +
+Prepare the distribution
++nsadmin:~$ cd /usr/local/src/aolserver +nsadmin:/usr/local/src/aolserver$ ./conf-clean +cat: BUILD-MODULES: No such file or directory +Done.+- +
++ + Put the name of the driver(s) that you want into + conf-db. This can be + postgresql, + oracle, or + both. +
++nsadmin:/usr/local/src/aolserver$ echo "postgresql" > conf-db+- +
+ + conf-inst should contain the + location where AOLserver is to be installed. This defaults to + /usr/local/aolserver, so we + don't need to change it. + +
- +
++ + conf-make should contain the + name of the GNU Make command on your system. It defaults to + gmake. You may need to change + this to make. +
++nsadmin:/usr/local/src/aolserver$ echo "make" > conf-make+- +
+Compile and install AOLserver and modules
++nsadmin:/usr/local/src/aolserver$ ./conf++ This takes about 5 minutes. All of the results are logged to + files in + /usr/local/src/aolserver/log. Make + sure to check these files to see if any errors occurred. +
++ ++
- +
+ You will now test to ensure AOLserver is running correctly. We'll + use the sample config file provided with AOLserver. This file + will attempt to guess your IP address and hostname. It will then + set up the server at port 8000 of that IP address. +
++nsadmin:/usr/local/src/aolserver$ cd +nsadmin:~$ ./bin/nsd -t sample-config.tcl++ As the AOLserver daemon starts up, you should see a few normal + warnings (listed below), which are safe to ignore. +
+Warning: nsd.tcl: nsssl not loaded -- key/cert files do not exist. -Warning: nsd.tcl: nscp not loaded -- user/password is not set. - -
- Test to see if AOLserver is working by starting Netscape - or Lynx, and surfing over to your web page:
You should see a Welcome to AOLserver page. If - this doesn't work, try going to - http://127.0.0.1:8000/. -
- Shutdown the test server:
The killall command will kill all processes with the - name nsd, but clearly this is not a good tool to use for - managing your services in general. We cover this topic in the ACS documentation.
On to installing the ArsDigita Community - System!
If you can't view the welcome page, it's likely there's a - problem with your server configuration. Start by viewing your AOLserver - log, which is in /usr/local/aolserver/log/server.log. - You should also try to find lines of the form:
+ The first warning means that the server is missing files for + running ssl, a necessary module + for encrypted HTTPS. See Scott Goodwin's excellent + documentation if you want to set up SSL. The second + warning means that the AOLserver control panel, a special module + for administering AOLserver, could not be loaded. If you're + interested in configuring nscp, please see the AOLserver + documentation. +
+ ++ ++ Test to see if AOLserver is working by starting + Mozilla or + Lynx, and surfing over to your + web page: +
++nsadmin:~$ lynx localhost:8000++ You should see a "Welcome to AOLserver" page. If this + doesn't work, try going to + http://127.0.0.1:8000/. If this + still doesn't work, check out the Troubleshooting AOLServer section below. +
++ + + ++ Shutdown the test server:
++nsadmin:~$ killall nsd++ The killall command will kill + all processes with the name nsd, + but clearly this is not a good tool to use for managing your + services in general. We cover this topic in the Keep AOLServer alive section. +
++ +If you can't view the welcome page, it's likely + there's a problem with your server configuration. Start by + viewing your AOLserver log, which is in + /usr/local/aolserver/log/server.log. + You should also try to find lines of the form:
+[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000) -[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections -
If you can find these lines, try entering the URL the server is - listening on. If you cannot find these lines, there must be an error - somewhere in the file. Search for lines beginning with the word - Error instead of Notice.
We used the following defaults while installing AOLserver:
| Variable | Value | Reason |
| AOLserver Username | nsadmin | AOLserver used to be NaviServer and this was the - standard username for the server. |
| AOLserver Directory | /usr/local/aolserver | When you use "make install" AOLserver 3.1 - will be installed here. Note that this is different from previous - versions of AOLserver; the change conforms to Red Hat Package Manager - (RPM) specifications. |
| nsadmin Home Directory | /home/aol31 | The various files needed and generated by running - AOLserver 3.1 processes should be located here, such as server .ini - and log files. This is described in depth in the next page of the - install guide. |
| AOLserver Groups | nsadmin,web,dba | You should have a UNIX group for the server files, - nsadmin, and a group for the web content, web. Note that in order to - connect to Oracle using svrmgrl, your user must be - part of the dba group and this capability is needed - to install the ACS. |
| AOLserver Source Directory | /tmp/aolserver | This is simply a convenient place to uncompress the - source. |
| ORACLE_HOME | /ora8/m01/app/oracle/product/8.1.6 | This is the default Oracle installation - directory. |
If you can find these lines, try entering the URL the server is + listening on. If you cannot find these lines, there must be an error + somewhere in the file. Search for lines beginning with the word + Error instead of + Notice.
+The sample-config.tcl file grabs + your address and hostname from your OS settings.
++set hostname [ns_info hostname] +set address [ns_info address]+
If you get an error that nssock can't get the requested address, + you can set these manually:
++#set hostname [ns_info hostname] +set hostname 127.0.0.1 +#set address [ns_info address] +set address 127.0.0.1+
+ If you get an error that nssock can't assign the requested port, + then that port may already be taken by another service. Try specifying + a different port in the config file. +
+ +Table of Contents
+ + +
+ +by Bryan Quinn -
Tcl API
-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
Tcl API
++ +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
+ ++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: -
ACS Applications: a "program or group of programs -designed for end users" (the Webopedia -definition); also known as modules, for historical reasons. +
++OpenACS Applications: a "program or group of programs +designed for end users" (the Webopedia +definition); also known as modules, for historical reasons. Examples of applications include Bboard and News. -
ACS Services: the aforementioned building blocks. -Examples of services include the ACS -Content Repository, the ACS Templating -System, and the ACS Kernel, which includes -APM.
An installation of the ACS includes the ACS Kernel, some services that +
+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 extend the kernel's functionality, and some applications intended for -end-users. Packages function as individual pieces of subsites. A subsite can contain multiple +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 -ACS Installation. Jack User discovers Jane's forum and includes a link to +OpenACS Installation. Jack User discovers Jane's forum and includes a link to it in his subsite. As interest in Jane's forum grows, she creates a subsite specializing in providing information about View cameras. This subsite now includes several package instances beyond Bboard; it could potentially include its own Ecommerce capabilities (ala Yahoo! Shopping). This could include a knowledge management application that allows users to spread expertise about view cameras and a portal application that links to reliable camera models -and resellers. Any subsite enabled package that is added to the ACS +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.
+for each instance, and managing the creation and release of new packages.
+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: -
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:
+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.
A typical ACS-backed site only uses a few of the modules included in the +break.
+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. -
Releasing a new version of the ACS was complicated, owing again to the +
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. -
There was no standard way for developers outside of ArsDigita to extend +
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 ACS Kernel, an ACS -service that is the only mandatory component of an ACS installation.
The ACS is a platform for web-based application software, and any software +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.
+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:
Borrowing from all of the above, ACS 3.3 introduces its own package -management system, the ACS Package Manager (APM), which consists of:
a standard format for APM packages (also called -"ACS packages"), including:
web-based tools for package management:
a registry of installed packages, database-backed and +including:
++Debian GNU/Linux and the Debian +Packaging manual +
+FreeBSD has the Ports +collection +
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:
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 -locations and names for files and patterns, for ACS 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 +
+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 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 ACS 3.3 system. However, while the +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 ACS 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 ACS -installations without doing a monolithic upgrade or reinstall.
The APM is composed of systems for accomplishing a set of package-related +subsites across the system, and be available for distribution to other OpenACS +installations without doing a monolithic upgrade or reinstall.
+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
Full instructions on how to prepare an ACS 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.
-- Informs the APM that this application is available for use. procedure register_application ( @@ -140,12 +326,15 @@ default null ); -
The procedure above registers an ACS application in the APM. It creates a -new ACS object and stores information about the package, such as its name, in -the APM data model. There is an analogous procedure for ACS services, called -apm.register_service.
To remove an application from the system, there are the calls + +
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.unregister_application and -apm.unregister_service.
-- Remove the application from the system. procedure unregister_application ( @@ -154,22 +343,29 @@ cascade_p in char default 'f' ); -
Use the cascade_p only if you want to completely remove the -package from the ACS.
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.
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.
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 @@ -190,26 +386,49 @@ 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:
+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:
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 @@ -230,9 +449,11 @@ 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 ACS.
procedure enable ( version_id in apm_package_versions.version_id%TYPE @@ -242,9 +463,11 @@ 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 @@ -259,10 +482,12 @@ 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.
-- Add an interface provided by this version. function add_interface( @@ -284,9 +509,11 @@ 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.
-- Add a requirement for this version. A requirement is some interface that this -- version depends on. @@ -309,8 +536,10 @@ 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. @@ -325,9 +554,12 @@ 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.
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 ACS API Documentation service -makes itself available on the ACS main site:
declare api_doc_id integer; begin api_doc_id := apm_service.new ( - instance_name => 'ACS API Browser', + instance_name => 'OpenACS API Browser', package_key => 'acs-api-browser', context_id => main_site_id ); @@ -380,16 +614,20 @@ 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.
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 ( @@ -435,8 +673,10 @@ 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 ( @@ -462,82 +702,212 @@ attr_value in apm_parameter_values.attr_value%TYPE ); -
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 ACS 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 ACS server, a row +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:
+Parameter information is maintained through two tables:
+A number of views are available for obtaining information about packages -registered in the APM.
+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.
The APM's user interface is part of the -ACS Administration Service. The UI is the primary -point of contact with APM by developers and administrators. It is part of ACS +
++apm_file_info + Provides a public interface for querying file information.
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.
APM has two parameters for configuring how it interacts with the UNIX +site-wide administration.
+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.
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 ACS 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.
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.
Table of Contents
+ + +
+ +| 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 | +
Table of Contents
+ + +
+ +Long before Bryan Quinn had anything to do with this guide, Adam - Farkas and Brian Stein conceived of the idea. Working with Bryan Quinn - for the first version were Doug Hoffman, Ravi Jasuja, Hiro Iwashima, Ryan - Lee, and Jonathan Goler. Many ArsDigita employees contributed - documentation, criticized the document, and tested every line. Among them - were Audrey Mcloghlin, Doug Harris, Zvi Boshernitzan, Michael Yoon, Cesar - Brea, Dennis Gregorovic, David Fullagar, and Chris Spears.
A few members of the photo.net community were brave enough to test the - documentation while it was still under development and contributed very - valuable suggestions and bug reports. Among them were Kevin Tupper, - Michael Duffy, Simon Carstensen, and Dave Bauer.
This document was assembled in part from previous documentation due to - the efforts of Tracy Adams, Greg Haverkamp, Philip Greenspun, and Jin - Choi. It was duly influenced by documents by Sean Yamamoto, David Cohen, - and Chris Rasch.
Several improvements were suggested that will be incorporated RSN - (hold bquinn to it) by Richard Li and Jon Griffin.
This documentation resulted from the collected efforts of employees at - ArsDigita and ACS users world-wide. If it is useful, it is because of the - distributed work of many enabled by the Internet. All mistakes and - shortcomings are due to the slow typing of Bryan Quinn.
All questions and comments regarding -this guide should be sent to acs@arsdigita.com. -
+Vinod Kurup put + together the January 2002 version of this guide from many sources of + information.
++ 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 + Mcloghlin, Doug Harris, Zvi Boshernitzan, Michael Yoon, Cesar Brea, + Dennis Gregorovic, David Fullagar, Chris Spears, Kevin Tupper, Michael + Duffy, Simon Carstensen, Dave Bauer, Tracy Adams, Greg Haverkamp, + Philip Greenspun, Jin Choi, Sean Yamamoto, David Cohen, Chris Rasch, + 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.
++ 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. +
+Table of Contents
+ + +
+ +Table of Contents
By Pete Su
- This document is a short tutorial on the Database API, meant for - experienced ACS developers to get a jump-start on its usage. For a - more complete discussion of the DB API, you can read - the documentation in - the kernel. -
- Here's a typical block of code from an ACS 3.x dynamic page: -
The Database Access API + + + + + + + + + ++ ++ By Pete Su and + Jon Salz. Modified + by Roberto Mello. +
++ +++ 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. +
++ ++ Here's a typical block of code from an OpenACS 3.x dynamic page: +
++set tcl_var "foo" set db [ns_db gethandle] -ns_db dml $db "begin transaction" +ns_db dml $db "begin transaction" -set sql "select +set sql "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' - " + " set selection [ns_db select $db $sql] set count 0 @@ -36,36 +74,50 @@ } ns_db releasehandle $db -
- Writing code like this had the following annoyances: + +
+ 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. -
+ 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. -
- Here is how you would code up the example above using the new API. -
+ 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. +
+ +
- There are several things to note here: + +
+ There are several things to note here: -
- No explicit code for grabbing and releasing handles. Usage of the - Database API implicitly deals with all handle management issues. -
- 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. -
- The new command db_foreach writes our old while loop for us. -
- Every SQL query has a name, meant to be unique within the server - instance (though this is not enforced). -
- Finally and most importantly, there is a new scheme for passing data - from a Tcl variable to the database, which we'll cover next. -
+ No explicit code for grabbing and releasing handles. Usage of the + Database API implicitly deals with all handle management issues. +
+ 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. +
+ The new command db_foreach writes + our old while loop for us. +
+ Every SQL query has a name, meant to be unique within the server + instance (though this is not enforced). +
+ 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 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: -
+ 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: first, if the literal value is a - huge string, then we waste a lot of time in the database server doing - useless parsing. 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. 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 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 - all previously parsed queries. If there are values in the where clause, - that is how the query is cached. It also performs bind variable - susbstitution after parsing the SQL statement. This means that SQL - statements that use bind variables will always match (assuming all else is - 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: -
+ There are a few problems with this: +
+++
- + If the literal value is a + huge string, then we waste a lot of time in the database server doing + useless parsing. +
+- + 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. +
+- +
++ 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 + 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 + all previously parsed queries. If there are values in the where clause, + that is how the query is cached. It also performs bind variable + susbstitution after parsing the SQL statement. This means that SQL + statements that use bind variables will always match (assuming all else is + 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: -
+ 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, bar, baz from some_table, some_other_table where some_table.id = some_other_table.id and some_table.condition_p = ? - "] + "] [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 - placeholders, and send those values along seperately. This seperate - 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: -
+ 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 + placeholders, and send those values along seperately. This seperate + 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: -
+ 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. -
- 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. You'll see the other styles - described in the detailed API document, but they're not important. -
- The Database API has several functions that wrap familiar parts of the - AOLserver database API. We won't cover the details of all the calls - here; instead, we'll list the most frequently used calls, with links - to further detail: + +
+ 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. +
++ 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. +
+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" -
- db_null
- Returns a value which can be used in a bind variable to represent - the SQL value null. You should use this instead of empty - strings when passing nulls to the database, because using the empty - string as the null value is not portable across databases. See - Nulls and Bind Variables. -
- - db_foreach - query_name sql { code } -
Runs a query returning multiple rows and executes a code block for - each row returned. -
- - db_1row - query_name sql
This is similar to the old ns_db 1row call.
- - db_0or1row - query_name sql
This is similar to the old call ns_db 0or1row
- - db_string - query_name sql -
Returns the first column of the result of a SQL query as a - string. Analogous to database_to_tcl_string and - database_to_tcl_string_or_null. -
- - db_list - query_name sql
Returns a Tcl list of values from the first column of each result row - of a SQL query. Similar to the old database_to_tcl_list. -
- - db_dml - query_name dml -
Performs a DML or DDL statement.
- - db_transaction - { code } -
Performs a block of Tcl code in the scope of a transaction.
- - db_abort_transaction - { code } -
Aborts a transaction.
($Id$)
+ 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.:
+
+
+set bind_vars [ns_set create]
+ns_set put $bind_vars user_id 123456
+ns_set put $bind_vars role "administrator"
+
+db_foreach user_group_memberships_by_role {
+ select g.group_id, g.group_name
+ from user_groups g, user_group_map map
+ where g.group_id = map.user_id
+ and map.user_id = :user_id
+ and map.role = :role
+} -bind $bind_vars {
+ # do something for each group in which user 123456 has the role
+ # 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
+ from user_groups g, user_group_map map
+ where g.group_id = map.user_id
+ and map.user_id = :user_id
+ and map.role = :role
+} -bind [list user_id 123456 role "administrator"] {
+ # do something for each group in which user 123456 has the role
+ # of "administrator"
+}
+
+
++ When processing a DML statement, Oracle coerces empty strings into + 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 + 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:
++ +# +# Given the table: +# +# create table foo ( +# bar integer, +# baz varchar(10) +# ); +# + +set bar "" +set baz "" + +db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)" +# +# the values of the "bar" and "baz" columns in the new row are both +# 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 + 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.:
++ +set bar [db_null] +set baz [db_null] + +db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)" +# +# sets the values for both the "bar" and "baz" columns to null + ++
+ 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.) +
++ 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 ++
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 ++
+ 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 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:
+
+
+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 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 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 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 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 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 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 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 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 + insert. Only one of -blobs, -clobs, + -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 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_release_unused_handles ++
Releases any allocated, unused database handles.
++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 + an exception. The variable errmsg will be bound in that scope. + If there is no on_error code, any errors will be propagated.
+Example:
+
+
+proc replace_the_foo { col } {
+ db_transaction {
+ db_dml "delete from foo"
+ db_dml "insert into foo(col) values($col)"
+ }
+}
+
+proc print_the_foo {} {
+ doc_body_append "foo is [db_string "select col from foo"]<br>\n"
+}
+
+replace_the_foo 8
+print_the_foo ; # Writes out "foo is 8"
+
+db_transaction {
+ replace_the_foo 14
+ print_the_foo ; # Writes out "foo is 14"
+ db_dml "insert into some_other_table(col) values(999)"
+ ...
+ db_abort_transaction
+} on_error {
+ doc_body_append "Error in transaction: $errmsg"
+}
+
+
+print_the_foo ; # Writes out "foo is 8"
+
+
++db_resultrows ++
Returns the number of rows affected or returned by the previous + statement. + + +
++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:
+
+
+proc lookup_the_foo { foo } {
+ db_with_handle db {
+ return [db_string unused "select ..."]
+ }
+}
+
+db_with_handle db {
+ # Now there's a database handle in $db.
+ set selection [ns_db select $db "select foo from bar"]
+ while { [ns_db getrow $db $selection] } {
+ set_variables_after_query
+
+ lookup_the_foo $foo
+ }
+}
+
+
+
+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]}
+
+
++
Table of Contents
Table of Contents
-In order to separate content and presentation, all ACS documentation will be marked up to conform to the -DocBook XML DTD -(Check the XML source of this document to get an idea of what it looks like). + + +
+ ++ By claus@arsdigita.com, with + additions by Roberto + Mello and the OpenACS Community +
++ ArsDigita created a good documentation ground for us to build + upon. Some sections of the documentation however, lack details + and examples, others simply are inexistent.Our goal is to give + OpenACS a superb documentation, so that users, developers and + administrators of OpenACS installations can enjoy the system. +
++ 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: +
++ 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 + and best of all, it's open-source. A growing community surrounds DocBook (has + mailing lists) + 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: + +
++ Always close your tags with corresponding end-tags and to + not use other tag minimization +
+ Write all elements and attributes in lowercase +
+ Quote all attributes +
+ You are going to need the following to work with the OpenACS + Docbook XML documentation: +
++ 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. +
++ The documentation for each package will make up a little "book" that is structured like this + - examples are emphasized: + -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 -and best of all, it's open-source. A growing community surrounds DocBook (has -mailing lists) -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 documentation for each package will make up a little "book" that is structured like this - - examples are emphasized: - - - -
-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 sources of these DocBook documents -to get an idea of how they are tied together. -
+ ... : ... + +
+ 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 + sources of these DocBook documents + to get an idea of how they are tied together. +
++ + 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> -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 Section 2.5.). -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. -
+ </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. +
++ + 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. +
++ + Linking falls into two different categories: inside the book you're making and outside: +
++ 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:
+-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: -
-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. -
+ And the output is: -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. -
+ - Find information about creating a package in + Making a Package -Linking falls into two different categories: inside the book you're making and outside: -
- 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:
+ Note that even though this is an empty tag, you have to either: +
+++
- +
+ Provide the end-tag, </xref>, or +
- +
+ 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:
+- Put this in your XML: + Put this in your XML: - - Find information about creating a package in - <xref linkend="packages-making-a-package"></xref>. + - Find information about what a package looks like in + <xref linkend="packages-looks"></xref>. - And the output is: + And the output is: - - Find information about creating a package in - Making a Package + - Find information about what a package looks like in + the section called “What a Package Looks Like” -
- Note that even though this is an empty tag, you have to either: -
If the section you link to hasn't a specified xreflabel-attribute, - the link is going to look like this:
+ 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
+- +
+ + ++ + If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just + a little different - Put this in your XML: + (<ulink>): - - Find information about what a package looks like in - <xref linkend="packages-looks"></xref>. +
+<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 + entities, which is exactly how you'll make an ampersand: & - And the output is: +
++ +++ 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>, + and + <imagedata>. + The news is that you have to provide two versions of all your graphics - one for the Web (probably a GIF or a JPEG) + 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"/> + </imageobject> + <imageobject> + <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/> + </imageobject> + <textobject> + <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. +
++ ++ + 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> - - Find information about what a package looks like in - Section 3.4. + </itemizedlist> ++- 2. How to make an <ol>
+- +
+ The ordered list is like the preceding, except that you use + <orderedlist> instead:
++ <orderedlist> + + <listitem><para>Stuff goes here</para><listitem> + <listitem><para>More stuff goes here</para><listitem> -
- 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. -
- - If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just - a little different + </orderedlist> + +
+ 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>:
++ <variablelist> + + <varlistentry> + <term>Heading (<dt>) goes here</term> + <listitem><para>And stuff (<dd>)goes here</para><listitem> + </varlistentry> - (<ulink>): + <varlistentry> + <term>Another heading goes here</term> + <listitem><para>And more stuff goes here</para><listitem> + </varlistentry> -+
+ </variablelist> +
+ + DocBook supports several types of tables, but in most cases, the + <informaltable> + is enough: +
++ <informaltable frame="all"> + <tgroup cols="3"> + <tbody> - ....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 - entities, which is exactly how you'll make an ampersand: & + <row> + <entry>a1</entry> + <entry>b1</entry> + <entry>c1</entry> + </row> -
-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 ;) - -
+ <row> + <entry>a2</entry> + <entry>b2</entry> + <entry>c2</entry> + </row> -To insert a graphic we use the elements -<mediaobject>, -<imageobject>, -and -<imagedata>. -The news is that you have to provide two versions of all your graphics - one for the Web (probably a GIF or a JPEG) -and one for print (EPS). Finally you should provide a brief description wrapped in -<textobject> - -in HTML this will be the ALT text. -
-Put your graphics in a separate directory ("images") and link to them -only with relative paths. -
+ <row> + <entry>a3</entry> + <entry>b3</entry> + <entry>c3</entry> + </row> -Here's how you make the DocBook equivalent of the three usual HTML-lists: -
- 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>: -
+ 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 ++ If you want cells to span more than one row or column, it gets a bit more complicated - check out + <table> + for an example. +
+ ++ +++ + 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">. +
++ +++ 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. +
++ ++++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 + 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 +++ ++
- + The LDP Author + Guide has a lot of good information, a table of + docbook elements and their "look" in HTML and lots of good links + for tools. +
+- +
+ David + Lutterkort + wrote an intro to the PSGML Mode in Emacs +
- +
+ For checking if your document is well-formed, James Clark's free Java parser, + XP, is recommended. (note that + it is not a validating parser, but as long as you follow the guidelines set forth in this + document, your XML will validate)
- +
+ DocBook Tool for Linux: + Let's you convert your docbook documents to a number of formats. Sometimes it's nice to see + how you stuff looks. NOTE: I only got these to + work with Docbook SGML, NOT with Docbook XML. If you are + able to make it work with our XML, please let us know. +
- +
+ AptConvert from PIXware is a Java editor that will produce + DocBook documents and let you transform them into HTML and PDF for a local preview before you submit. +
+ In the process of transforming your HTML into XML, + HTML tidy + can be a a handy tool to make your HTML "regexp'able". + Brandoch Calef has made a + Perl script + that gets you most of the way. - </itemizedlist> -
- The ordered list is like the preceding, except that you use - <orderedlist> instead:
- 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>:
- -DocBook supports several types of tables, but in most cases, the -<informaltable> -is enough: -
-With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: -
-If you want cells to span more than one row or column, it gets a bit more complicated - check out -<table> -for an example. -
- -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">. -
-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 and the -source of this document -for examples. -
-David Lutterkort wrote an intro to the PSGML Mode in Emacs -
-For checking if your document is well-formed, James Clark's free Java parser, -XP, is recommended. (note that -it is not a validating parser, but as long as you follow the guidelines set forth in this -document, your XML will validate)
-DocBook Tool for Linux: -Let's you convert your docbook documents to a number of formats. Sometimes it's nice to see -how you stuff looks. -
-AptConvert from PIXware is a Java editor that will produce -DocBook documents and let you transform them into HTML and PDF for a local preview before you submit. -
-In the process of transforming your HTML into XML, -HTML tidy -can be a a handy tool to make your HTML "regexp'able". -Brandoch Calef has made a -Perl script -that gets you most of the way. - -
-You shouldn't worry about publishing you documents - that's the idea of separating content from presentation. -
-Exactly how the documentation will be published is not finalized yet. The current idea is to keep -all the documentation in raw XML under CVS and then parse it with what ever style-sheet we choose upon -release. -
| Document Revision # | +Action Taken, Notes | +When? | +By Whom? | +
|---|---|---|---|
| 0.3 | ++ Added OpenACS information, updatet 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 | +
Table of Contents
+ + +
+ +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: -
-Why do we need a naming convention? +
+We can quickly identify and fix any errors.
We can reliabily modify or drop constraints
+
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 | +
<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.
If the constraint name is still too long, you should consider rewriting your entire data model :) -
Notes:
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
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; @@ -67,16 +166,53 @@ 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 + +
+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? -
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 +
++
+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 +"Cannot insert null value into column"), we recommend naming not null constraints to be consistent in our naming of all constraints. -
Table of Contents
By michael@arsdigita.com and -aure@arsdigita.com
+ + +
+ +To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas: -
+
+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.
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:
-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: -
Put data model files in /www/doc/sql, and name them +
+Present a form to the user
Present a confirmation page to the user
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: -
-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 +
+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 just the directory name, for both relative links (subdir/) and absolute links (/top-level-dir/). If linking to the directory in which -the page is located, use the empty string (""), which +the page is located, use the empty string (""), which browsers will resolve correctly. -
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. -
+ +
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: -
+ +
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 +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 { @@ -116,35 +231,47 @@ {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 +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
-For shared Tcl library files, use ad_library after +
+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 { @@ -153,51 +280,63 @@ @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
+ +
For SQL and other non-Tcl source files, the following file header structure is recommended: -
-Of course, replace "--" with the comment delimiter + +
+Of course, replace "--" with the comment delimiter appropriate for the language in which you are programming. -
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: -
+ +
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 @@ -210,20 +349,56 @@ 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. -
+ + +
+ +Table of Contents
-ACS version numbers help identify at a high-level what is in a + + +
+ ++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 -change in the architecture of the system, e.g. ACS 2 to ACS 3. A -change in the minor version number signifies the addition of -new modules and minor data model changes, e.g. ACS 3.1 to ACS 3.2. -The final release number indicates the relative maturity of a +"version number" is really just a string of the form: +
+++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 +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 release and marks things like bug fixes; it follows the ordered progression: -
+ +
So typical release version numbers would be: -
-The first is a relatively mature release of the ACS 3.2 base code -and the second is a non-public release of ACS 4.0 that probably still +
++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: -
-In the future, ArsDigita packages should follow this same + +
+In the future, OpenACS packages should follow this same convention on version numbers. -
So what distinguishes an alpha release from a beta +
+So what distinguishes an alpha release from a beta release? Or from a production release? We follow a specific set of -rules for how ACS makes the transition from one state of maturity to -the next.
Every release must pass the minimum requirements that it cleanly -installs and cleanly upgrades from the previous version of ACS. 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 +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 +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 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.
Table of Contents
Table of Contents
By You
-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 ACS Core. Furthermore, it may be easier in some circumstances -to join certain sections together, e.g. it may make sense to discuss -the data model and transactions API together instead of putting them -in separate sections. And on occasion, you may find it easier to -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 -programmers who want to maintain/extend the software, AND parties -interested in evaluating software quality. -
-When applicable, each of the following items should receive its own link: -
-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 - 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).
-Also worthy of treatment in this section: -
-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. -
-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. -
-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 -software, the reasons for this should be discussed here; our sales -team needs to be ready for inquiries regarding features our software -lacks.
-Note that such a discussion may differ from a discussion of a -package's potential future improvements. -
-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 -flexibility/generality of a system typically entails a decrease in the -simplicity and efficiency of that system. Thus a developer must decide -to put a higher value on some attributes over others: this section -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:
Areas of interest to developers:
-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 - interface to database objects and legal transactions - the latter - 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 -that we've previously always looked at the data models as key, and -seldom spent much effort on the API (e.g. putting raw SQL in pages to -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 ACS 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. -
-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 -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 -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 - your package. Consider grouping legal transactions according to - the invoking user class, i.e. transactions by an ACS-admin, by - subsite-admin, by a user, by a developer, etc.
-In this section, discuss user interface issues and pages to be built; -you can organize by the expected classes of users. These may include: -
-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 -different system documents, these users should herein be designated as -"the developer," "the ACS-admin," "the sub-admin," and "the user," -respectively. -
-Finally, note that as our templating system becomes more entrenched -within the ACS, this section's details are likely to shift from UI -specifics to template interface specifics. -
-Under ACS 4, parameters are set at two levels: at the global level by -the ACS-admin, and at the subsite level by a sub-admin. In this -section, list and discuss both levels of parameters. -
-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. -
-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 |
By You +
++ 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 + the data model and transactions API together instead of putting them + in separate sections. And on occasion, you may find it easier to + 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 + programmers who want to maintain/extend the software, AND parties + interested in evaluating software quality. +
++ 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
+ 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 + 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).
+ Also worthy of treatment in this section: +
+When applicable, a careful demarcation between the + functionality of this package and others which - at least + 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. +
++ 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. +
++ 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 + software, the reasons for this should be discussed here; our sales + team needs to be ready for inquiries regarding features our software + lacks.
+ Note that such a discussion may differ from a discussion of a + package's potential future improvements. +
++ 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 + flexibility/generality of a system typically entails a decrease in the + simplicity and efficiency of that system. Thus a developer must decide + to put a higher value on some attributes over others: this section + 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
+ 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 + interface to database objects and legal transactions - the latter + 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 + that we've previously always looked at the data models as key, and + seldom spent much effort on the API (e.g. putting raw SQL in pages to + 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. +
++ 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 + 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 + 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 + 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.
++ 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
+ 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 + different system documents, these users should herein be designated as + "the developer," "the OpenACS-admin," "the sub-admin," and "the user," + 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. +
++ Under OpenACS 4, 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. +
++ 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. +
++ 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
+ 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 | +
Table of Contents
High level information: What is the ACS?
High level information: What is OpenACS?
+Table of Contents
+ +Table of Contents
Table of Contents
+ +Table of Contents
+ + +
+ +| 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 | +
Table of Contents
+ + +
+ +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
| 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 | +
- +
- The ArsDigita Community System (ACS)
+The OpenACS Community System
- The Basic ACS + Basic OpenACS Installed Packages
Please visit the -Documentation Central -or shoot at claus@arsdigita.com. +OpenACS bboards +or shoot email at vinod@kurup.com or rmello@cc.usu.edu. Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,22 +1,77 @@ - -7. Kernel Documentation
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation+ + + + +Table of Contents
- 1. Overview
- 2. ACS 4 Object Model Requirements
- 3. ACS 4 Object Model Design
- 4. ACS 4 Permissions Requirements
- 5. ACS 4 Permissions Design
- 6. ACS 4 Groups Requirements
- 7. ACS 4 Groups Design
- 8. ACS 4 Subsites Requirements
- 9. ACS 4 Subsites Design Document
- 10. ACS 4 Package Manager Requirements
- 11. ACS 4 Package Manager Design
- 12. ACS 4 Security Requirements
- 13. ACS 4 Security Design
- 14. ACS 4 Security Notes
- 15. ACS 4 Request Processor Requirements
- 16. ACS 4 Request Processor Design
- 17. Database Access API
- 18. Documenting Tcl Files: Page Contracts and Libraries
- 19. Bootstrapping ACS
- Compared to its predecessors, version 4 of the ArsDigita Community - System (ACS) 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 ACS 4 Kernel, which handles system-wide necessities - such as metadata, security, users and groups, subsites, and - package management and deployment. -
The ACS 4 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. -
ACS 4 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. -
Chapter 7. Kernel Documentation + + + + + + + + + ++ ++ + + Index: openacs-4/packages/acs-core-docs/www/more-developer-info.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/more-developer-info.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/more-developer-info.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/more-developer-info.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,2 +1,62 @@ - -++Table of Contents
++
+- Overview
+- OpenACS 4 Object Model Requirements
+- OpenACS 4 Object Model Design
+- OpenACS 4 Permissions Requirements
+- OpenACS 4 Permissions Design
+- OpenACS 4 Groups Requirements
+- OpenACS 4 Groups Design
+- OpenACS 4 Subsites Requirements
+- OpenACS 4 Subsites Design Document
+- OpenACS 4 Package Manager Requirements
+- OpenACS 4 Package Manager Design
+- OpenACS 4 Security Requirements
+- OpenACS 4 Security Design
+- OpenACS 4 Security Notes
+- OpenACS 4 Request Processor Requirements
+- OpenACS 4 Request Processor Design
+- Database Access API
+- Documenting Tcl Files: Page Contracts and Libraries
+- Bootstrapping OpenACS
+5. Other Developer Resources
Home : Documentation : Part III. For ACS Developers : 5. Other Developer Resources+ + + + +Table of Contents
Chapter 5. Other Developer Resources + + + + + + + + + ++ ++ + + Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/object-identity.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,34 +1,92 @@ - -++Table of Contents
+ +3. Object Identity
Home : Documentation : Part III. For ACS Developers : 5. Other Developer Resources : 3. Object Identity+ + + Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,170 +1,359 @@ - -+ + +
+ +Object Identity + + + + + + + + + ++ + ++key to eliminating redundant code and replacing it with generic object +level services. +One of the major design features of OpenACS 4 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.0 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.0 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.0 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$)($Id$)+3. ACS 4 Object Model Design
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 3. ACS 4 Object Model Design+ + + Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,69 +1,171 @@ - -Table of Contents
- 3.1. Essentials
- 3.2. Introduction
- 3.3. History
- 3.4. Summary and Design Considerations
- 3.5. Data Model
- 3.6. API
- 3.7. Future Improvements/Areas of Likely Change
- 3.8. Authors
- 3.9. Revision History
+ + +
+ +OpenACS 4 Object Model Design + + + + + + + + + + + +2. ACS 4 Object Model Requirements
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 2. ACS 4 Object Model Requirements+ + + Index: openacs-4/packages/acs-core-docs/www/packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/packages.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/packages.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,331 +1,596 @@ - -Table of Contents
- 2.1. I. Introduction
- 2.2. Vision Statement
- 2.3. System Overview
- 2.4. Use-cases and User-scenarios
- 2.5. Related Links
- 2.6. Requirements: Data Model
- 2.7. Requirements: API
- 2.8. Revision History
+ + +
+ +OpenACS 4 Object Model Requirements + + + + + + + + + ++ +++SQL> select sysdate from dual; +By Pete Su -
++ +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:
All of these services involve relating extra information and services to -application data objects, examples of which include:
In the past, developers had to use ad-hoc and inconsistent schemes to -interface to the various "general" services mentioned above. Since +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 -amount of code repetition in applications, is a primary goal of ACS 4. Thus +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 -any object within a given instance of ACS 4. The term "metadata" +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 ACS, and typically corresponds to a single row within the -relational database.
+The ACS 4 Object Model must address five high-level requirements that -repeatedly exhibit themselves in the context of existing services in ACS 3.x, -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 ACS 3.x, there are +services. The term "object" refers to any entity being represented +within the OpenACS, and typically corresponds to a single row within the +relational database.
++ +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 +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 ACS 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 +"page" data (static or dynamic) to one or more user comments on the page, by constructing a unique identifier for each page. This identifier is usually a combination of the table in which the data is stored, and the value of the primary key value for the particular page. This idiom is referred to -as the "(on_which_table + on_what_id)" method for identifying +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: +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: 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 ACS 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 +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 developer. Until the implementation of the general permissions system, every -ACS 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:
The first row represents an entry in User 123's personal address book, +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, 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 ACS 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 ACS 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 @@ -74,193 +176,493 @@ 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 ACS 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 ACS -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 +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 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 +"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 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 ACS applications define simple relationships between application -objects, and tag those relationships with extra data. In ACS 3.x, this was -done using mapping tables. The user/groups module has the most +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 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 user_group_member_fields_map tables to allow developers to attach custom attributes to group members. In fact, these custom 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. As a -historical note, in ACS 3.x, user/groups was the only part of the system that +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 ACS 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.
+The Object Model package is a combination of data model and a procedural -API for manipulating application objects within an ACS instance. The OM -allows developers to describe a hierarchical system of object types +dependencies.
++ +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 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 ACS 4 Kernel data model. The -other parts of the Kernel data model include:
Each of these is documented elsewhere at length.
+ + + Index: openacs-4/packages/acs-core-docs/www/objects.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/objects.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/objects.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,13 +1,44 @@ - -The data model for the object system provides support for the following -kinds of schema patterns that are used by many existing ACS 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.
++ + +++ +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 ACS 3.x, modules use ad-hoc means to construct unique identifiers for +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 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 ACS 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 -with unique identifiers (unique within a given ACS instance) and with +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 ACS 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 ACS -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 ACS 4 object system +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 ACS 3.x data models, -such as:
40.10 Generic Retrieval
Attributes should be stored so that they are retrievable in a way that is +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 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 ACS 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 ACS 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 -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. -That is, contexts can be logically "contained" within other +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. +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 -"site-wide" context in some sense. I wanted to note this fact for +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.
+The API should let programmers accomplish the following actions:
++ +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 +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 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" +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 ACS, and these services will likely make extensive use of the +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 ACS 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?
++
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 +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?
+ + + ++ ++requirements on relation types.+
+ + ++ + + + + +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 09/06/2000 +Pete Su ++ + +0.9 +Edited for ACS 4 Beta release. +09/30/2000 +Kai Wu +2. ACS 4 Data Models and the Object System
Home : Documentation : Part III. For ACS Developers : 4. ACS Developer's Guide : 2. ACS 4 Data Models and the Object System+ + + Index: openacs-4/packages/acs-core-docs/www/oracle.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/oracle.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/oracle.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,345 +1,623 @@ - -Table of Contents
- 2.1. Overview
- 2.2. How to Use Objects
- 2.3. When to Use Objects
- 2.4. Design Guidance
- 2.5. Summary
By Pete Su
+-Developing data models in ACS 4 is much like developing data models -for ACS 3, save for the implementation. As usual, you need to examine + + +
+ +OpenACS 4 Data Models and the Object System + + + + + + + + + ++ + ++ ++ +++Developing data models in OpenACS 4 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), @@ -17,51 +48,73 @@ 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: -
-In ACS 4, the key to enabling these types of services on your +
+++
- +
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.
+In OpenACS 4, 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 -you use them for anyway?". The short answer: objects are anything +question anyone asks is usually "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 ACS 4, or that may be reusable in +managed by any central service in OpenACS 4, or that may be reusable in the context of future applications. Every object in the system is represented using a row in the acs_objects table. This 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: -
+ +
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 + 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."
+ ++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 make some calls to use our notes table as the basis for a -new object type. Object types are analogous to classes in +new object type. Object types are analogous to classes in programming languages such as C++ and Java. For example, in Java a class defines a set of attributes that store data and a set of methods -that run code. In ACS 4, we use one or more Oracle tables to store the +that run code. In OpenACS 4, 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 @@ -71,13 +124,19 @@ 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. -
+
+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: -
++during the earlier created the package. Then, do the following: +
++ ++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', @@ -90,7 +149,8 @@ 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 @@ -99,13 +159,15 @@ 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 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. -
-We can stop here and not bother to register the usual ACS 3.x + +
+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. -
+ ++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) ) -+ +
Again, the usual creation_date and modified_date columns are absent since they already exist in acs_objects. Also, note the constraint we have added @@ -160,11 +230,17 @@ use the acs_objects table to find objects will transparently find any objects that are instances of any subtype of acs_objects. -
+ ++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: -
+ +
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 -that's not stored directly in the table you defined. The ACS 4 Object +that's not stored directly in the table you defined. The OpenACS 4 Object System defines these attributes on the type acs_object since all objects should have these attributes. Internally, there are tables that store this information for you. Most of the data is pretty self-explanatory and reflects attributes that existed in the earlier -ACS 3.x data models, with the exception of the context_id +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 +is used by the permissions system in this way: if no permissions are explicitly attached to the object, then the object inherits its permissions from the context. For -example, if I had told you how to use the permissions system to specify that an -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 +example, if I had told you how to use the permissions system to specify that an +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. -
+ +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. -
+ +
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; @@ -286,74 +373,96 @@ drop package note; drop table notes; -+ ++While it is generally hard to give general design advice without knowing anything about a particular application, you should follow the following rule of thumb when deciding when to hook part of your data model to the object system: -
-Anything in your data model that needs to be available to general ACS +
++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. -
+ ++In this section we cover some overall guidelines for designing data -models that are meant to be integrated with the ACS object +models that are meant to be integrated with the OpenACS object system. -
-There are two basic rules you should follow when designing ACS 4 data +
++There are two basic rules you should follow when designing OpenACS 4 data models: -
The reason behind these two rules is pretty straightforward: First, -the ACS Object system itself is meant to be a generic and reusable +the OpenACS Object system itself is meant to be a generic and reusable tool for any application to use for basic services. Second, in order -for this to work, the various parts of the ACS Objects data model must +for this to work, the various parts of the OpenACS Objects data model must be interpreted in the same way by all applications that use the data model. Therefore, assigning any application-specific semantics to any part of the core data model is a bad thing to do, because then the 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. -
- +
+
+ ++
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, +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. -
+
+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 @@ -365,29 +474,69 @@ when to use inherited attributes is fairly straightforward, but requires a good amount of thought at design time even for simple applications. -
+ ++Hooking into the OpenACS 4 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$)($Id$)+5. Installing Oracle 8.1.6
Home : Documentation : Part II. For ACS Admins : 2. Installing on Unix/Linux : 5. Installing Oracle 8.1.6+Table of Contents
NOTE: -This document was 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
You can obtain the software through a variety of methods:
Order a CD from the Oracle Store. -There is a link under the heading Buying Tips that says "Learn -how to trial Oracle software." Click this for instructions on how to -make your order. The cost is currently $39.95 with delivery estimated between -3-4 business days. - - -
Request a free demonstration CD. At the -Oracle Downloads page, click on the appropriate version of Oracle 8.1.6 -Release 2 for your OS. You should see a "Try Online" link. After -filling out some information forms, you should be able to order a version of -the CD. This takes about 2-3 weeks for delivery. - - -
You can download Oracle from the Technet ftp site. The Linux version is -at ftp://ftp.oracle.com/pub/www/otn/linux/oracle8i/oracle8161_tar.gz
Note that the Oracle tarball that you will download is huge (> -250MB).
Oracle 8.1.6 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.
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 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. +
++ ++ You can obtain the software through a variety of methods (You'll need + to become a member of technet.oracle.com, which is + free): +
++
- +
+ 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. +
- +
+ 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 -xzvf oracle8161_tar.gz - -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 Section 5.10..
+Though Oracle 8.1.6 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 user other than root and -then doing a su -. This command gives you full root access.
+ ++ + It used to be possible to get a free CD by mail, but + I can no longer find the link for that option. +
+ +++ 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”. +
++ ++ 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. +
++
- +
+ Login as a non-root user and start X by typing + startx + +
+joeuser:~$ startx+- +
+ Open a terminal window type and login as root +
+joeuser:~$ su - +Password: *********** +root:~#+- +
-
Start X by typing startx - - -
Open a terminal window type and login as 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.
-Now change the oracle account password -
You will be prompted for the New Password and Confirmation of that -password.
Setup the installation location for Oracle
While Oracle can reside in a variety of places in the file system, -ArsDigita has adopted '/ora8' as the base directory.
Note: the Oracle install needs about 1 GB free on -'/ora8' to install successfully.
Set up the oracle user environment
Log in as the user oracle
In the same terminal window, type the following.
Use a text editor to edit the .bash_profile file in the -oracle account home directory.
-You may get this error trying to start emacs: -
+ 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++ You will be prompted for the New Password and Confirmation of + that password. +
+ +- +
+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 + 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+- +
+ Set up the oracle user's + environment +
++
- +
++ Log in as the user + oracle by typing the + following: +
++joeuser:~$ su - oracle +Password: ********+- +
+ Use a text editor to edit the + .bash_profile file in the + oracle account home + directory. +
++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. - --If so, do the following. -
-Try this procedure anytime you get an Xlib connection refused error. - - -
Add the following lines to ~oracle/.bash_profile:
+ If so, open a new terminal window and do the following: +
++joeuser:~$ xhost +localhost++ Now, back in the oracle terminal: +
++oracle:~$ export DISPLAY=localhost:0.0 +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.6 +export ORACLE_HOME=$ORACLE_BASE/product/8.1.7 export PATH=$PATH:$ORACLE_HOME/bin export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib export ORACLE_SID=ora8 export ORACLE_TERM=vt100 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data -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 any lines like the following -
+ 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 + any lines like the following +
+# NLS_LANG=american -# export NLS_LANG - -These lines will change the Oracle date settings and will break the -ArsDigita Community System (ACS) because ACS depends on the ANSI date format, -YYYY-MM-DD dates.
Log out as oracle - -
-
Log back in as oracle and double check that your environment variables -are as intended -
-If it worked, you should see: -
+ 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+- +
+ 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++ 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.6 -ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data - -If not, try adding the files to ~oracle/.bashrc instead of -.bash_profile. Then logout and log back in again. Also, be -certain you are doing su - and not just su. The -- means that .bashrc and .bash_profile -will be evaluated.
Make sure that /bin, /usr/bin, and -/usr/local/bin are in your path by typing:
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
Log in as the user oracle and start X if not already -running -
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 -
If you are installing from the tarball, the install script is located in -the 'Oracle8iR2' directory that was created when you expanded the -archive. -
-Check to make sure the file is there. -
-If you don't see runInstaller you are in the wrong -directory. - -
Run the installer -
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.6"
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 -~oracle/.bash_profile as you did in Section 5.3.
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 a root: - - -
Open a new terminal window, then type: - -
+ If not, try adding the files to + ~/.bashrc instead of + .bash_profile. Then logout and + log back in again. Also, be certain you are doing + su - oracle and not just + su oracle. The + - means that + .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++ 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 +
+ + + ++ ++
- +
++ Log in as oracle and + start X if not already running. Start a new terminal: +
++joeuser:~$ xhost +localhost +joeuser:~$ su - oracle +Password: ********** +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+- +
++ 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++ Check to make sure the file is there. +
++oracle:/where/oracle/Disk1$ ls +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++ A window will open that welcomes you to the 'Oracle Universal + Installer' (OUI). Click on + "Next" +
+- +
++ 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 ; You should see: Creating Oracle Inventory pointer file (/etc/oraInst.loc) -Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall. -# exit -$ exit - -Click "Retry" - -
The "Available Products" screen in the OUI: -
The "Installation Types" screen -
The "Available Product Components" screen -
The "Component Locations" screen in the OUI -
The "Privileged Operation System Groups" screen in the OUI -
The "Create a Database" screen in the OUI - -
The "Summary" screen in the OUI - -
Check the "Space Requirements" section to verify you have -enough disk space for the install. - - -
Check that "(91 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. - - - -
-
- + + +
+ Click "Retry" +
- +
++ The "Available Products" screen in the OUI: +
+++
- +
+ Select "Oracle 8i Enterprise Edition 8.1.7.1.0" +
- +
Click "Next"
- +
++ The "Installation Types" screen +
+++
- +
+ Select the "Custom" installation type. +
- +
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 - +Password: ********* +root:~# /ora8/m01/app/oracle/product/8.1.7/root.sh ; You should see the following. Creating Oracle Inventory pointer file (/etc/oraInst.loc) Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall. -# /ora8/m01/app/oracle/product/8.1.6/root.sh +# /ora8/m01/app/oracle/product/8.1.7/root.sh Running Oracle8 root.sh script... The following environment variables are set as: ORACLE_OWNER= oracle - ORACLE_HOME= /ora8/m01/app/oracle/product/8.1.6 + ORACLE_HOME= /ora8/m01/app/oracle/product/8.1.7 ORACLE_SID= ora8 Enter the full pathname of the local bin directory: [/usr/local/bin]: -Press ENTER here to accept default of /usr/local/bin +Press ENTER here to accept default of /usr/local/bin Creating /etc/oratab file... @@ -351,293 +629,462 @@ 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. - - -Do not follow the instructions on deleting trace and log files, it is not -necessary. - - -
Go back to the pop-up window and click "OK" - - -
The "Configuration Tools" screen in the OUI - -
The "Welcome" screen in the "net 8 Configuration -Assistant" - -
The "Listener Configuration, Listener Name" screen in the -"Net 8 Configuration Assistant" - -
The "Listener Configuration, Select Protocols" screen in the -"Net 8 Configuration Assistant" - -
The "Listener Configuration TCP/IP Protocol" screen in the -"Net 8 Configuration Assistant" - -
The "Listener Configuration, More Listeners" screen in the -"Net 8 Configuration Assistant" -
The "Listener Configuration Done" screen in the "Net 8 -Configuration Assistant" -
The "Naming Methods Configuration" screen in the "Net 8 -Configuration Assistant" - -
The "Done" screen in the "Net 8 Configuration -Assistant" -
The "End of Installation" screen in the OUI - -
Congratulations, you have just installed Oracle 8.1.6 Server! However, you -still need to create a database which can take about an hour of -non-interactive time, so don't quit yet.
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.
Make sure you are running X. Open up a terminal and su to oracle and then -run the dbassist program. -
The "Welcome" screen in the Oracle Database Configuration Agent -(ODCA) -
The "Select database type" screen in the ODCA - -
The "Primary Database Type" window in ODCA -
The "concurrent users" screen of the ODCA -
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; aD uses 8192 on the big Solaris machines). - - -
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.6/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 -database. Assuming your $ORACLE_HOME matches our default of -/ora8/m01/app/oracle/product/8.1.6, the following will open the -file for editing. -
Add the following line to the end: - -
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. -
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 CRTL-ALT-BACKSPACE, but make -sure you have saved any files you were editing. You should now be returned to -a text shell prompt. If you get sent to a graphical 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: - - -
- -In some instances, Oracle will save the file to -/ora8/m01/app/oracle/product/8.1.6/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.
For this step, open up a terminal and su to oracle as usual. You should be -running X and Netscape for this phase.
You need to download the "Oracle Acceptance Test" file. -It's available here and at http://photo.net/wtr/oracle/acceptance-sql.txt. -Save the file to /tmp - -
In the oracle shell, copy the file. - -
Once you've got the acceptance test file all set, stay in your term -and type the following: - -
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.
- + +
+ Do not follow the instructions on deleting trace + and log files, it is not necessary. +
+root:~# 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. +
- +
+ 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. +
+ ++ +++ 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. +
+++
- +
++ 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+- +
++ 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 + 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+- +
++ Add the following line to the end: +
++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+- +
+ 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 + CRTL-ALT-BACKSPACE, but make + sure you have saved any files you were editing. You should now be + returned to a text shell prompt. If you get sent to a graphical + 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++ 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. +
++ ++ 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+- +
+ Once you've got the acceptance test file all set, stay in + your term and type the following: +
++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.
++oracle:~$ svrmgrl SVRMGR> connect internal -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): -
- +
+ 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; -Verify that your date settings are correct. -
-If you don't see a date that fits the format YYYY-MM-DD, -please read Section 5.8.. - - -
At this point we are going to hammer your database with an intense -acceptance test. This usually takes around 30 minutes. -
- +
++ Verify that your date settings are correct. +
++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 @@ -647,56 +1094,118 @@ ---------- 2000-06-10 -SQL> - -Many people encounter an error regarding maximum key -length:
+ Many people encounter an error regarding maximum + key length: +
+ERROR at line 1: -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 the ACS into a pre-existing database. -Unfortunately, the only solution is to create a new database with a block -size of at least 4096. For instructions on how to do this, -see Section 5.5. above. You can set the -parameter using the 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.
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 shipped in the -Linux distribution does not work out of the box. The fix is simple. Follow -these directions to apply it. First, save dbstart -to /tmp. Then login, and su to oracle.
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.
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)
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. -
- +
Save the file & quit the terminal. +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 + create a new database with a block size of at least + 4096. For instructions on how to + do this, see the section called “Creating the First Database” above. You + can set the parameter using the + 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. +
++ ++ 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 + shipped in the Linux distribution does not work out of the + box. The fix is simple. Follow these directions to apply + 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+- +
- -
You need a script to automate startup and shutdown. Save oracle8i.txt in /tmp. Then login as -root and install the script.
Test the script by typing the following commands and checking the output.
+
- +
+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) +
+- +
++ 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+- +
+ 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++ + 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: Oracle Server Manager Release 3.1.6.0.0 - Production @@ -713,9 +1222,9 @@ ORACLE instance shut down. SVRMGR> Server Manager complete. -Database "ora8" shut down. +Database "ora8" shut down. -# /etc/rc.d/init.d/oracle8i start +root:~# /etc/rc.d/init.d/oracle8i start Oracle 8i auto start/stop Starting Oracle8i: SQL*Plus: Release 8.1.6.0.0 - Production on Sat Jun 10 17:56:02 2000 @@ -734,34 +1243,81 @@ Database opened. SQL> Disconnected -Database "ora8" warm started. - -If it worked, then run these commands to make the startup and shutdown -automatic.
+ + If it worked, then run these commands to make the startup and + shutdown automatic. +
++
- +
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 - -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
Now issue the following commands (still as root).
Test the listener automation by running the following commands and -checking the output.
+ + + +Debian users:
++root:~# update-rc.d oracle8i defaults + Adding system startup for /etc/init.d/oracle8i ... + /etc/rc0.d/K20oracle8i -> ../init.d/oracle8i + /etc/rc1.d/K20oracle8i -> ../init.d/oracle8i + /etc/rc6.d/K20oracle8i -> ../init.d/oracle8i + /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++ + 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 +oracle:~$ chmod 700 /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr +oracle:~$ chmod 700 /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr +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++ 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: LSNRCTL for Linux: Version 8.1.6.0.0 - Production on 10-JUN-2000 18:28:49 @@ -779,11 +1335,11 @@ (c) Copyright 1998, 1999, Oracle Corporation. All rights reserved. -Starting /ora8/m01/app/oracle/product/8.1.6/bin/tnslsnr: please wait... +Starting /ora8/m01/app/oracle/product/8.1.7/bin/tnslsnr: please wait... TNSLSNR for Linux: Version 8.1.6.0.0 - Production -System parameter file is /ora8/m01/app/oracle/product/8.1.6/network/admin/listener.ora -Log messages written to /ora8/m01/app/oracle/product/8.1.6/network/log/listener.log +System parameter file is /ora8/m01/app/oracle/product/8.1.7/network/admin/listener.ora +Log messages written to /ora8/m01/app/oracle/product/8.1.7/network/log/listener.log Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost.localdomain)(PORT=1521))) Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC))) @@ -797,17 +1353,24 @@ Trace Level off Security OFF SNMP OFF -Listener Parameter File /ora8/m01/app/oracle/product/8.1.6/network/admin/listener.ora -Listener Log File /ora8/m01/app/oracle/product/8.1.6/network/log/listener.log +Listener Parameter File /ora8/m01/app/oracle/product/8.1.7/network/admin/listener.ora +Listener Log File /ora8/m01/app/oracle/product/8.1.7/network/log/listener.log Services Summary... PLSExtProc has 1 service handler(s) ora8 has 1 service handler(s) -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
+ This test will verify that the listener is operating + normally. Login into the database using the listener naming + convention. +
++ sqlplus + username/password/@SID +
++root:~# su - oracle +oracle:~$ sqlplus system/alexisahunk@ora8 SQL> select sysdate from dual; @@ -816,71 +1379,243 @@ 2000-06-10 SQL> exit -$ exit -# - -Now run chkconfig on the listener8i script.
Test the automation
As a final test, reboot your computer and make sure Oracle comes up. You -can do this by typing
-Log back in and ensure that Oracle started automatically. -
+
- +
+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:
++ 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 + /etc/rc1.d/K19listener8i -> ../init.d/listener8i + /etc/rc6.d/K19listener8i -> ../init.d/listener8i + /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++ + 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++ Log back in and ensure that Oracle started automatically. +
++joeuser:~$ su - oracle +oracle:~$ sqlplus system/alexisahunk@ora8 -SQL> exit - -Congratulations, your installation of Oracle 8.1.6 is complete.
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 or for -the default case, -$ORACLE_HOME/dbs/initora8.ora
-You test whether this solved the problem by firing up -sqlplus and typing: -
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:
+ Congratulations, your installation of Oracle 8.1.7 is + complete. +
+ ++ ++ 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 + or for the default case, + $ORACLE_HOME/dbs/initora8.ora +
++nls_date_format = "YYYY-MM-DD"++ You test whether this solved the problem by firing up + sqlplus and typing: +
++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; -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.
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:
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 nls_lang line:
Log back in again. If adding the nls_date_format line -doesn't help, you can ask for advice in our -web/db forum.
Dropping a tablespace
Run sqlplus as the dba:
To drop a user and all of the tables and data owned by that user:
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. -
For more information on Oracle, please consult the documentation.
We used the following defaults while installing Oracle.
Variable Value Reason ORACLE_HOME /ora8/m01/app/oracle/product/8.1.6 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$)+ 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. +
++ 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++ 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 + nls_lang line: +
++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. +
++ +++
- +
+ Dropping a tablespace +
+++
- +
++ Run sqlplus as the dba: +
++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;+- +
++ 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;++ For more information on Oracle, please consult the documentation. +
++ ++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$)+3. ACS 4 Packages
Home : Documentation : Part III. For ACS Developers : 4. ACS Developer's Guide : 3. ACS 4 Packages+Table of Contents
- 3.1. Overview
- 3.2. Why package your software?
- 3.3. The APM
- 3.4. What a Package Looks Like
- 3.5. Making a Package
- 3.6. The Site Map and Package Instances
- 3.7. Summary
- 3.8. Additional Reading
By Pete Su and Bryan Quinn
-This document is a guide on how to write a software package for the -ArsDigita Community System. ACS packages are installed and maintained -with the ACS 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. -
-To answer this question, we should examine how ACS servers were -organized in the past. We will assume throughout this document that -the page root for your server is called ROOT. In ACS -3.2.x and earlier, a typical server might have a file system behind it -that looked something like this: -
OpenACS 4 Packages + + + + + + + + + ++ ++ By Pete Su and + Bryan Quinn +
++ +++ 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. +
++ ++ 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/ - parameters/ +ROOT/ + bin/ + parameters/ ad.ini - tcl/ + tcl/ core tcl libraries here - www/ - admin/ - bboard/ + www/ + admin/ + bboard/ site wide admin for bboard - intranet/ + intranet/ site wide admin for intranet ... and so on for all modules ... - bboard/ + bboard/ pages for bboard - admin/ + admin/ other admin pages for bboard - intranet/ + intranet/ pages for bboard - admin/ + admin/ other admin pages for intranet - doc/ + doc/ documentation sql/ core and application data models here ... and so on for all modules ... --Later ACS 3.x installs also had a packages directory, but -the 3.x package manager was only experimental. -
-In previous versions of ACS, you wrote a new application like this: -
-This structure is very simple, and worked well in a world where the -ACS was basically a single monolithic entity. But, this organization -made it difficult to distribute modules as independent packcages, because -the pieces of each module are strewn all over the tree in at least 3 -or 4 different areas. -
-Here is how an ACS 4 server is laid out: -
+ 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/. +
+ 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 server is laid out: +
+-ROOT/ - bin/ - packages/ - acs-admin/ - acs-api-browser/ - acs-content-repository/ - acs-core-docs/ - acs-developer-support/ - acs-kernel/ - acs-ldap-authentication/ - acs-messaging/ - acs-subsite/ - acs-templating/ - acs-test-harness/ - acs-util/ - acs-workflow/ - bboard/ +ROOT/ + bin/ + packages/ + acs-admin/ + acs-api-browser/ + acs-content-repository/ + acs-core-docs/ + acs-developer-support/ + acs-kernel/ + acs-ldap-authentication/ + acs-messaging/ + acs-subsite/ + acs-templating/ + acs-test-harness/ + acs-util/ + acs-workflow/ + bboard/ bboard.info - sql/ + sql/ data model - tcl/ + tcl/ tcl library code - www/ - admin/ + www/ + admin/ administration pages other pages - doc/ + doc/ documentation - message-catalog/ - news/ - notification/ - page/ - tcl/ + message-catalog/ + news/ + notification/ + page/ + tcl/ bootstrap code - www/ + 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 -two major advantages: -
-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 ACS 4, this tool is called 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: -
-In addition for packages that are applications, the APM is repsonsible -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 -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 ACS 4 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 -one or more arbitrary URLs in a running site. -
++ +
+ 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 + 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. +
+ 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, this tool is called 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.
+ 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 + 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 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 + 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. +
++ +++ + 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: +
+-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 +ROOT/ + +-- packages/ APM Root | - +-- notes/ Package Root + +-- notes/ Package Root | | | | | +-- sql/ | | | - | | +-- notes-create.sql Data Model Creation Script - | | +-- notes-drop.sql Data Model Drop Script - | | +-- *.sql Data Model Files + | | +-- oracle/ + | | | | + | | | +-- notes-create.sql Data Model Creation Script for Oracle + | | | +-- notes-drop.sql Data Model Drop Script + | | | +-- *.sql Data Model Files + | | +-- postgresql/ + | | | | + | | | +-- notes-create.sql Data Model Creation Script for PostgreSQL + | | | +-- notes-drop.sql Data Model Drop Script + | | | +-- *.sql Data Model Files | +-- tcl/ | | | - | | +-- notes-procs.tcl Tcl Library - | | +-- notes-init.tcl Tcl Initialization - | | +-- *.tcl Tcl Library Files + | | +-- 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/ | | | - | | +-- admin/ Administration UI - | | | +-- tests/ Regression Tests - | | | | +-- index.tcl Regression Test Index Page - | | | | +-- ... Regression Tests - | | | +-- index.tcl Administration UI Index Page - | | | +-- ... Administration UI Pages + | | +-- admin/ Administration UI + | | | +-- tests/ Regression Tests + | | | | +-- index.tcl Regression Test Index Page + | | | | +-- ... Regression Tests + | | | +-- index.tcl Administration UI Index Page + | | | +-- ... Administration UI Pages | | | - | | +-- doc/ Documentation - | | | +-- index.tcl Documentation Index Page - | | | +-- ... Administration Pages - | | +-- index.tcl UI Index Page - | | +-- index.adp UI Index Template - | | +-- *.tcl UI Logic Scripts - | | +-- *.adp UI Templates - | +-- notes.info Package Specification File + | | +-- doc/ Documentation + | | | +-- index.tcl Documentation Index Page + | | | +-- ... Administration Pages + | | +-- index.tcl UI Index Page + | | +-- index.adp UI Index Template + | | +-- index.xql Queries for UI Index page + | | +-- *.tcl UI Logic Scripts + | | +-- *.adp UI Templates + | | +-- *-oracle.xql Oracle-specific Queries + | | +-- *-postgresql.xql PostgreSQL-specific Queries + | +-- 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 ++ +++ 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: +
++
- 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. +
- +
Click the button "Create Package". +
- +
At this point, APM will create a directory called + ROOT/packages/notes. +
- +
+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. +
+- +
Now go back to the main management page for the notes + If your package has parameters, create them using the "Manage + Parameter Information" link.
- +
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: +
+-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 to support the package. The name must match - the convention below or the package will not be installed correctly. - sql/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/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. This can be done by including - @@ filename in the creation or drop scripts. See - the Oracle SQL*Plus documentation for examples. sql/*.sql 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 ACS Package Manager (APM). It specifies - information about the package including its parameters and its - files. notes.info -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: - -
-
- 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. -
Click the button Create Package. -
At this point, APM will create a directory called -ROOT/packages/notes. -
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 ACS has automatic mechanisms for loading and reloading -.tcl files for code, it does not do the same thing for -data model files. -
Now go back to the main management page for the notes -If your package has parameters, create them using the Manage -Parameter Information link.
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: -
-Now you can start developing the package. In addition to writing code, -you should also consider the tasks outlined in the package submission guidelines. -
+-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 -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 -ACS 3.x, but also much more flexible. -
-In ACS 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 ACS 4, 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 -ACS 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 -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 -administrators to build sites that look to the user like a collection -of many indepdendent applications that actually run on a single shared -code base. The request-processor document shows -you how ACS 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 -default available at /acs-admin/site-map. Use the -interface here to add a new sub-folder called notes to -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: + + +
+ + Now you can start developing the package. In addition to writing code, + you should also consider the tasks outlined in the package submission guidelines. +
+ ++ 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 + 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, 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 + 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 + 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 + administrators to build sites that look to the user like a collection + of many indepdendent 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 + default available at /acs-admin/site-map. Use the + interface here to add a new sub-folder called notes to + 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: -
-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 -to supporting subsites. -
-The APM performs the following tasks in an ACS 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. -
($Id$)+ 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 + to supporting subsites. +
+ ++ +++ 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. +
+ ++ + + + Index: openacs-4/packages/acs-core-docs/www/parties.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/parties.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/parties.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,26 +1,64 @@ - -+($Id$)+2. Parties in ACS 4
Home : Documentation : Part III. For ACS Developers : 5. Other Developer Resources : 2. Parties in ACS 4+ + + Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,10 +1,51 @@ - -Table of Contents
- 2.1. Introduction
- 2.2. The Data Model
- 2.3. Views
- 2.4. Extending The Parties Data Model
+ + +
+ +Parties in OpenACS 4 + + + + + + + + + + +5. ACS 4 Permissions Design
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 5. ACS 4 Permissions Design+ + + Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,90 +1,277 @@ - -Table of Contents
- 5.1. Essentials
- 5.2. Introduction
- 5.3. Historical Considerations
- 5.4. Competitive Analysis
- 5.5. Design Tradeoffs
- 5.6. Data Model Discussion
- 5.7. Legal Transactions
- 5.8. API
- 5.9. User Interface
- 5.10. Configuration/Parameters
- 5.11. Future Improvements/Areas of Likely Change
- 5.12. Authors
- 5.13. Revision History
+ + +
+ +OpenACS 4 Permissions Design + + + + + + + + + + + +4. ACS 4 Permissions Requirements
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 4. ACS 4 Permissions Requirements+ + + Index: openacs-4/packages/acs-core-docs/www/permissions.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/permissions.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/permissions.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,31 +1,68 @@ - -Table of Contents
- 4.1. Introduction
- 4.2. Vision Statement
- 4.3. System Overview
- 4.4. Use Cases and User Scenarios
- 4.5. Related Links
- 4.6. Functional Requirements
- 4.7. Behavioral Requirements
- 4.8. Revision History
+ + +
+ +OpenACS 4 Permissions Requirements + + + + + + + + + ++ + +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.
++ ++++
+ + ++ + + + + +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 +7. Groups, Context, Permissions
Home : Documentation : Part III. For ACS Developers : 4. ACS Developer's Guide : 7. Groups, Context, Permissions+ + + Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,47 +1,97 @@ - -Table of Contents
- 7.1. Overview
- 7.2. Groups
- 7.3. Permissions
- 7.4. Object Context
- 7.5. Example
- 7.6. Summary
By Pete Su
+-The ACS 4 Permissions system allows developers and administrators to + + +
+ +Groups, Context, Permissions + + + + + + + + + ++ + ++ ++ +++The OpenACS 4 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 -site. Therefore, ACS 4 has two auxiliary mechanisms for making this +administrator would want to explicitly set access control +rights for every user and every object on a +site. Therefore, OpenACS 4 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. -
+ ++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 ACS 4 object type system, +contained a meta-data system much like the OpenACS 4 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 @@ -35,34 +72,39 @@ employees. Obviously, you'd want every member of an office employee group to automatically be a member of the whole company employee group. -
-In ACS 3.x, you also could not express the fact that group A should +
++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 in the real world, though not as often. A good example is an organization like Greenpeace that can have as members both individuals and organizations: although the Sierra Club may be an organization member of Greenpeace, its members are not necessarily members of Greenpeace. -
-ACS 4 solves both of these modeling problems by introducing a new -abstraction called a party. Parties have a recursive +
++OpenACS 4 solves both of these modeling problems by introducing a new +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), @@ -75,52 +117,64 @@ 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 ACS 3.x users table contained. -
-Finally, we define two relations, one for group membership and -one for group composition. The composition relation allows us +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 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 ACS 4 or ACS 4 Groups Design. -
++permissions work. For further detail, you can look at Parties in OpenACS 4 or OpenACS 4 Groups Design. +
++ +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 ACS 4, a privilege models the right to perform some operation on +
++In OpenACS 4, 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 implement access control by granting users some combination of -read. write or execute privileges on files and directories. In ACS 4, +read. write or execute privileges on files and directories. In OpenACS 4, the table of privileges is organized hierarchically so that developers can define privileges that aggregate some set of privileges together. For example, if we have read, write, create and delete privileges, it might be convenient to combine them into a new privilege -called "admin". Then if we grant a user this privilege she is +called "admin". Then if we grant a user this privilege she is automatically granted all the child privileges that the privilege -contains. The ACS 4 kernel data model actually defines these +contains. The OpenACS 4 kernel data model actually defines these privileges as follows: -
begin acs_privilege.create_privilege('read'); @@ -137,44 +191,94 @@ 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. -
+-In ACS 4, an object context is a generalization of the scoping -mechanism introduced in ACS 3.x. "Scoping" and "scope" are terms best +
++ +++In OpenACS 4, 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 +� +� +... +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 +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 ACS 4, rather than breaking the world into a limited set of scopes, -every object lives in a single context. A context is just an +
++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 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 @@ -186,11 +290,12 @@ 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 -privileges whenever we create a message, which is tedious. In ACS 4, +privileges whenever we create a message, which is tedious. In OpenACS 4, a reasonable thing to do is to create an object representing a forum, and point the context_id field of a new message at the forum. Then, suppose we grant every user in the system read-access to @@ -199,14 +304,17 @@ 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 ACS +are "magic" in some sense because they are created by default by OpenACS for a specific purpose. The object default_context represents the root of the context hierarchy for the entire site. All permission searches walk up the tree to this point and then stop. If @@ -217,25 +325,33 @@ 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. -
+ ++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 +"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: -
+ +
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: -
+ +
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: -
+ +
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: -
+ +
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 ACS 4 template system +The if tag is something that the OpenACS 4 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 @@ -337,15 +462,50 @@ 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. -
+ ++OpenACS 4 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$)($Id$)+4. Programming with AOLserver
Home : Documentation : Part III. For ACS Developers : 5. Other Developer Resources : 4. Programming with AOLserver+ + + Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/psgml-mode.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,52 +1,122 @@ - -Table of Contents
+ + +
+ +Programming with AOLserver + + + + + + + + + + +3. Using PSGML mode in Emacs
Home : Documentation : Part III. For ACS Developers : 6. Engineering Standards : 3. Using PSGML mode in Emacs+Table of Contents
- 3.1. What it is
- 3.2. Where to get it
- 3.3. Using CATALOG files
- 3.4. What to tell emacs
- 3.5. What is a DOCTYPE ?
- 3.6. How to use it
- 3.7. Further reading
+ + +
+ +Using PSGML mode in Emacs + + + + + + + + + ++ + ++element is a sect1. ++ +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:
+ (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)) - (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode)) - (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode)) - (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode)) + (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode)) + (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode)) + (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode)) + (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode)) - (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG") + (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) @@ -58,28 +128,105 @@ (setq sgml-set-face t) (setq-default sgml-indent-data t) ;; Some convenient key definitions: - (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type) - (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)))) + (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type) + (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)))) -+All SGML and XML documents that should conform to a DTD have to declare a + +
+ +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
+ <!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") + 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.
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. + ++ + + + + Index: openacs-4/packages/acs-core-docs/www/release-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/release-notes.html 19 Oct 2001 02:05:55 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/release-notes.html 2 Feb 2002 03:47:32 -0000 1.4 @@ -1,51 +1,90 @@ + - -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.2 Alpha - -This is an alpha release of OpenACS 4.2. 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 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 Ars Digita's original documentation -on installing under Unix/Linux or -Windows. The basic process is unchanged, and we -expect to update the documentation for our beta release. -
After installation, the full documentation set for acs-core provided in the original -aD release can be found by visiting -http://[your-host]/doc. -
Note on installing packages
-The APM will die if you attempt to install more than a few -packages at once in the Oracle version. This is due to the list of required -files being stored in a varchar which is limited in Oracle to being 4,000 bytes long. -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 Edition and OpenACS 4 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'. +
+ +OpenACS 4.2-beta Release Notes + + + + + + + + + ++ ++ Index: openacs-4/packages/acs-core-docs/www/request-processor.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/request-processor.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/request-processor.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,77 +1,135 @@ - --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. As -with the Oracle version, there are steps you must take manually in order to -get this feature working. -
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 + This is a beta release of OpenACS 4.2. 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 + 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 Installing on Windows. Note that the Windows + documentation is not current for OpenACS4. +
++ After installation, the full documentation set can be found by visiting + http://[your-host]/doc. Not all pieces are updated for OpenACS 4 at + this moment. +
++ +++ 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 Edition + and OpenACS 4 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. +
++ +++ 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 Minimal @@ -201,7 +240,33 @@ Test Coverage: Minimal Suggested Status: Alpha Comments: Don tested personally - -+ +($Id$)+4. The Request Processor
Home : Documentation : Part III. For ACS Developers : 4. ACS Developer's Guide : 4. The Request Processor+ + + Index: openacs-4/packages/acs-core-docs/www/requirements-template.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/requirements-template.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/requirements-template.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,81 +1,242 @@ - -Table of Contents
- 4.1. Overview
- 4.2. The Old Way
- 4.3. The New Way
- 4.4. Basic API
By Pete Su
+-This document is a brief introduction to the ACS 4 Request Processor; -more details can be found in the ACS 4 Request Processor Design. Here we cover the high level concepts behind the + + +
+ +The Request Processor + + + + + + + + + ++ + +++ ++This document is a brief introduction to the OpenACS 4 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. -
+-In older versions of the ACS, the mapping between URLs and pages was -simple. AOLserver (the usual webserver for the ACS) would find the +
++ +++In older versions of the OpenACS, the mapping between URLs and pages was +simple. AOLserver (the usual webserver for the OpenACS) would find the appropriate file by appending the server's page-root to the path in 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 +request for a URL like "http://foo-service.com/bar.html" would cause the server to look in the filesystem for /web/foo-service/www/bar.html, and return that file. -This was simple enough, but ACS did not provide a clean centralized +This was simple enough, but OpenACS did not provide a clean centralized mechanism for the following requirements of larger web services: -
+-To achieve this functionality above in ACS 3.x, developers used an ad +To achieve this functionality above in OpenACS 3.x, developers used an ad hoc combination of AOLserver filters, the ns_perm call, -special purpose code in pages, and other procedures. In ACS 4, the -Request Processor, along with the ACS Package Manager, centralizes and +special purpose code in pages, and other procedures. In OpenACS 4, the +Request Processor, along with the OpenACS Package Manager, centralizes and unifies this functionality, making it more transparent and readily available to developers. -+
- +
Support for more flexible mappings from URLs to content +
- +
Robust user authentication +
- +
Page level access control +
+ ++The 4.0 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.
-+
- Stage 1: Search Site Map
+
++
- 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 Section 8.). This data model maps URLs to objects representing +discussed in the section called “Writing OpenACS 4 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 ACS 4 Request Processor Design. The page +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
- +
+
+- 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 +(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
- +
+
- Stage 3: Authorization
+Next, the Request Processor checks if the user has appropriate access -privileges to the requested part of the site. In ACS 4, access control +privileges to the requested part of the site. In OpenACS 4, access control is dictated by the permissions system. In -this case, the RP checks if the user has "read" priviledges on the +this case, the RP checks if the user has "read" priviledges on the object in the site map specified by the URL. This object is typically a package instance, but it could easily be something more granular, 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
- +
+
- 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" +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 @@ -81,66 +139,127 @@ can be thought of as a replacement for filters and registered procs, 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 ACS 4 Request Processor Design. -
+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. -
+ ++ +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$)($Id$)+5. System/Application Requirements Template
Home : Documentation : Part III. For ACS Developers : 6. Engineering Standards : 5. System/Application Requirements Template+ + + Index: openacs-4/packages/acs-core-docs/www/rp-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/rp-design.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/rp-design.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,53 +1,130 @@ - -Table of Contents
By You
-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. -
++ + +
+ +System/Application Requirements Template + + + + + + + + + ++ + ++ 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. + ++ +++ 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. +
++ +-Very broadly, describe how the system meets a need of a business, -group, the ACS 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. -
-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 -here, e.g. if it's an application-level package for ACS 4, briefly -describe how it uses kernel services, like permissions or subsites. -
-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. -
-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. -
Include all pertinent links to supporting and related material, -such as:
-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
-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
- The system should not make any assumptions about how pages should - look or function. -
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 ACS 4 Package Manager Requirements. -
-Besides writing requirements in natural language, consider using the -following techniques as needed: -
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 -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 -documents, sometimes a high-level ER diagram is useful for -requirements as well.
-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. -
+ +++ 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 + here, e.g. if it's an application-level package for OpenACS 4, briefly + describe how it uses kernel services, like permissions or subsites. +
++ +++ 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. +
++ +++ 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. +
++ ++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)
+ +++ 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
++ 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
++ The system should not make any assumptions about how pages should + look or function. +
+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 Package Manager Requirements. +
++ Besides writing requirements in natural language, consider using the + following techniques as needed: +
+++
- +
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 + 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 + documents, sometimes a high-level ER diagram is useful for + requirements as well.
+ ++ ++ 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. +
+16. ACS 4 Request Processor Design
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 16. ACS 4 Request Processor DesignTable of Contents
- 16.1. Essentials
- 16.2. Introduction
- 16.3. Related Systems
- 16.4. Terminology
- 16.5. System Overview
- 16.6. Site Nodes
- 16.7. Request Environment
+ + +
+ +OpenACS 4 Request Processor Design + + + + + + + + + ++ + + + + Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/rp-requirements.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,25 +1,131 @@ - -15. ACS 4 Request Processor Requirements
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 15. ACS 4 Request Processor Requirements+ + + Index: openacs-4/packages/acs-core-docs/www/security-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/security-design.html 19 Dec 2001 18:33:22 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/security-design.html 2 Feb 2002 03:47:32 -0000 1.4 @@ -1,52 +1,196 @@ - -Table of Contents
- 15.1. Introduction
- 15.2. Vision Statement
- 15.3. System Overview
- 15.4. Related Links
- 15.5. Requirements
+ + +
+ +OpenACS 4 Request Processor Requirements + + + + + + + + + ++ + +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
+13. ACS 4 Security Design
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 13. ACS 4 Security Design+ + + Index: openacs-4/packages/acs-core-docs/www/security-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/security-notes.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/security-notes.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,40 +1,75 @@ - -Table of Contents
- 13.1. Essentials
- 13.2. Introduction
- 13.3. Design
- 13.4. API
- 13.5. Future Improvements
- 13.6. Vulnerability Analysis
+ + +
+ +OpenACS 4 Security Design + + + + + + + + + + +14. ACS 4 Security Notes
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 14. ACS 4 Security Notes+ + + Index: openacs-4/packages/acs-core-docs/www/security-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/security-requirements.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/security-requirements.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,46 +1,145 @@ - -Table of Contents
+ + +
+ +OpenACS 4 Security Notes + + + + + + + + + ++ + ++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. -
+it is called by the request processor. ++
++ +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:
if { [ad_secure_conn_p] && ![ad_login_page] } { - set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]] + set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]] if { [empty_string_p $s_token_cookie] || [string compare $s_token_cookie [lindex [sec_get_session_info $session_id] 2]] != 0 } { # token is incorrect or nonexistent, so we force relogin. - ad_returnredirect "/register/index?return_url=[ns_urlencode [ad_conn url]?[ad_conn query]]" + ad_returnredirect "/register/index?return_url=[ns_urlencode [ad_conn url]?[ad_conn query]]" } } -The source code must also be edited if the user login pages have been -moved out of an ACS system. This information is contained by the -ad_login_page procedure in security-procs.tcl:
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_proc -private ad_login_page {} { @@ -43,15 +78,45 @@ } { set url [ad_conn url] - if { [string match "*register/*" $url] || [string match "/index*" $url] } { + if { [string match "*register/*" $url] || [string match "/index*" $url] } { return 1 } 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$)($Id$)+12. ACS 4 Security Requirements
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 12. ACS 4 Security Requirements+ + + Index: openacs-4/packages/acs-core-docs/www/subsites-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/subsites-design.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/subsites-design.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,48 +1,109 @@ - -Table of Contents
- 12.1. Introduction
- 12.2. Vision Statement
- 12.3. Security System Overview
+ + +
+ +OpenACS 4 Security Requirements + + + + + + + + + + +9. ACS 4 Subsites Design Document
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 9. ACS 4 Subsites Design Document+ + + Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,56 +1,214 @@ - -Table of Contents
- 9.1. Essentials
- 9.2. Introduction
- 9.3. Historical Considerations
- 9.4. Competitive Analysis
- 9.5. Design Tradeoffs
- 9.6. API
- 9.7. Data Model Discussion
- 9.8. User Interface
- 9.9. Configuration/Parameters
- 9.10. Future Improvements/Areas of Likely Change
- 9.11. Authors
+ + +
+ +OpenACS 4 Subsites Design Document + + + + + + + + + ++ + ++*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.
+solvable by configuration instead of coding. +An ACS 4 subsite is a managed suite of applications that work together for +demand.
++ + +++ +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 -support, i.e. very low level support from the core ACS 4 data model. For +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 ACS 4 components implicitly support -subsites as a whole.
+The subsites problem actually has several quite diverse origins. It was +is, in fact, a discussion of how core OpenACS 4 components implicitly support +subsites as a whole.
++ +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 -ACS installation to behave as multiple unscoped ACS installations so that one -ACS install could serve multiple communities. Each piece of application data -was tagged with a "scope" consisting of the (user_id, group_id, +"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 ACS4 implementation of -subsites addresses.
+ +The current implementation of package instances and subsites allows +dominant, this is the primary problem that the OpenACS4 implementation of +subsites addresses.
++ +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.
+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.
++ ++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)
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.
create table site_nodes ( node_id constraint site_nodes_node_id_fk @@ -135,7 +199,9 @@ ); -The following package is provided for creating nodes.
The following package is provided for creating nodes.
+create or replace package site_node as @@ -180,32 +246,88 @@ 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 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.
+The primary elements of the subsite user interface consist of the subsite +data model.
++ +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.
+ +The current subsites implementation addresses the most basic functionality +subsite administrator would want to do.
++ +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 -this falls under is "inter-package communication". An actual +this falls under is "inter-package communication". An actual implementation of this could be anything from clever use of configuration parameters to lots of package level introspection. Another area that is -currently underdeveloped is the ability to "tar up" and distribute +currently underdeveloped is the ability to "tar up" and distribute 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.
+ + ++8. ACS 4 Subsites Requirements
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 8. ACS 4 Subsites Requirements+ + + Index: openacs-4/packages/acs-core-docs/www/subsites.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/subsites.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/subsites.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,107 +1,165 @@ - -Table of Contents
+ + +
+ +OpenACS 4 Subsites Requirements + + + + + + + + + + + +8. Writing ACS 4 Application Pages
Home : Documentation : Part III. For ACS Developers : 4. ACS Developer's Guide : 8. Writing ACS 4 Application Pages+ + + Index: openacs-4/packages/acs-core-docs/www/tcl-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tcl-doc.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tcl-doc.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,42 +1,93 @@ - -Table of Contents
- 8.1. Overview
- 8.2. Application Instances and Subsites
- 8.3. Using Forms
- 8.4. How it All Fits
- 8.5. Summary
+ + +
+ +Writing OpenACS 4 Application Pages + + + + + + + + + + +18. Documenting Tcl Files: Page Contracts and Libraries
Home : Documentation : Part III. For ACS Developers : 7. Kernel Documentation : 18. Documenting Tcl Files: Page Contracts and Libraries+ + + Index: openacs-4/packages/acs-core-docs/www/templates.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/templates.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/templates.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,32 +1,69 @@ - -Table of Contents
- 18.1. The Big Picture
- 18.2. ad_page_contract
- 18.3. ad_library
+ + +
+ +Documenting Tcl Files: Page Contracts and Libraries + + + + + + + + + + +6. Using Templates in ACS 4
Home : Documentation : Part III. For ACS Developers : 4. ACS Developer's Guide : 6. Using Templates in ACS 4+ + + Index: openacs-4/packages/acs-core-docs/www/unix-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/unix-install.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/unix-install.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/unix-install.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,20 +1,66 @@ - -Table of Contents
- 6.1. Overview
- 6.2. Entering Notes
- 6.3. Summary
By Pete Su
+-The ACS 4 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 + + +
+ +Using Templates in OpenACS 4 + + + + + + + + + ++ + ++ ++ +++The OpenACS 4 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 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 ACS Notes application, this +
++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. -
+ ++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 @@ -35,17 +72,19 @@ 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 { - Form to add a note in ACS Notes. + Form to add a note in OpenACS Notes. @author Jane Coder @creation-date 11 Oct 2000 @@ -66,17 +105,20 @@ where forum_id = :user_id } -set page_title "Add a note for $user_name" -set submit_label "Add" -set target "note-add-2" +set page_title "Add a note for $user_name" +set submit_label "Add" +set target "note-add-2" set note_id [db_nextval acs_object_id_seq] -ad_return_template "note-add" +ad_return_template "note-add" -+ +
Some things to note about this code: -
+
- +
-The procedure ad_page_contract is +
++
+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 of input values from the HTTP request (i.e. form variables) and in @@ -87,82 +129,125 @@ string value. Later on, we'll see how to use more powerful kinds of data sources for representing multiple rows from an SQL query. You also include overall documentation for the page in the contract, and -ACS has automatic tools that extract this documentation and make it +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: -
+ +
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 "@" +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: Master templates allow you do centralize display code that is used throughout an application in a single file. In this case, we intend to have a master template that does the standard page headers and footers for us - create the master.adp file, which looks like this: -
+ +
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. -
+ +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 ACS 4, the +queries and application logic, and another for display. In OpenACS 4, 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$)($Id$)+2. Installing on Unix/Linux
Home : Documentation : Part II. For ACS Admins : 2. Installing on Unix/Linux+ + + + +Table of Contents
-This document is a guide to installing the ArsDigita Community -System (ACS). It is targeted for first time users who may not be -familiar with Oracle and AOLServer, but who are familiar with UNIX - -with an emphasis on Linux. However, for the purposes of running the -ACS, Linux is not substantially different from other UNIX systems, -such as Solaris or HP-UX. -
-Assuming you have a computer with a network connection, before -starting installation of ACS please refer to the following: -
If it's a PC and you're going to use Linux, then read everything.
If it's a UNIX box, skip the Linux chapter and read everything else.
If it's a Windows box, read How to install ACS on Windows - instead.
If you already have Oracle up and running, then skip to the - AOLServer 3.1 chapter and read from there.
-If you are interested in learning more about the ACS first, then -please read Chapter Three: Scalable -Systems for Online Communities from Philip & Alex's Guide to -Web Publishing, and this document on Using the -ArsDigita Community System. -
Chapter 2. Installing on Unix/Linux + + + + + + + + + ++ ++ + + Index: openacs-4/packages/acs-core-docs/www/win-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/win-install.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/win-install.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/win-install.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,2 +1,60 @@ - -++Table of Contents
+ +3. Installing on Windows
Home : Documentation : Part II. For ACS Admins : 3. Installing on Windows+ + + + +Table of Contents
Chapter 3. Installing on Windows + + + + + + + + + ++ ++ + + Index: openacs-4/packages/acs-core-docs/www/win2k-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/win2k-installation.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/win2k-installation.html 17 Oct 2001 20:39:26 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/win2k-installation.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,50 +1,127 @@ - -++Table of Contents
+ +2. How to install ACS on Windows2000
Home : Documentation : Part II. For ACS Admins : 3. Installing on Windows : 2. How to install ACS on Windows2000+ + + Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml 24 Dec 2001 19:31:42 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -10,10 +10,10 @@Table of Contents
- 2.1. Overview
- 2.2. Prerequisites
- 2.3. Your Oracle installation
- 2.4. The ArsDigita binary installation
- 2.5. Untar the ACS
- 2.6. Feeding Oracle the Data Model
- 2.7. Configuring AOLServer
- 2.8. Configuring ACS itself
- 2.9. Starting the Service
- 2.10. Configuring Permissions
- 2.11. Adding Yourself as a User and Making Yourself a Sysadmin
- 2.12. Closing Down Access
- 2.13. Where to Find What
- 2.14. Making sure that it works
- 2.15. Running Multiple Instances of the ACS
By Matthew Burke and Curtis Galloway
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/
++ + +
+ +How to install ACS on Windows2000 + + + + + + + + + ++ + ++ +++
- +
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/ +
+ +With the recent release of a win32 version of AOLserver, it is now possible to run the ACS on Windows2000 and Windows98. This document explains the steps necessary to get the ACS 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 ACS. -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 - under "ArsDigita AOLserver 3 Binary Distribution for Win32." + 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.
+
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)
It is helpful if you have Oracle interMedia Text for full-text searches. + specific to the version you are downloading.
++ +++
- +
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)
- +
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 ACS, 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 ACS installation instead of WinZip and zsh.
+- When you install Oracle, a good rule of thumb is "every default - setting is wrong." We will not discuss Oracle configuration here + use to perform the ACS installation instead of WinZip and zsh.
++ +++ 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 ACS 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 NT) 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:
++
- +
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 and run the following query: select sysdate from - dual;
Otherwise you will need to perform a little registry surgery as - follows:
+Otherwise you will need to perform a little registry surgery as + follows:
++
- +
Run regedit and navigate down the registry keys to + HKEY_LOCAL_MACHINE\Software\ORACLE.
Choose the appropriate subtree; this will be HOME0 if you only have on einstallation of Oracle. @@ -54,181 +131,312 @@ HOME2, etc. Choose the subtree that corresponds to the Oracle installtion you wish to use with the ACS.
-- +
If the NLS_DATE_FORMAT key is already present, +
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.
- +
Verify the date format by logging into the database using SQL Plus + create it. Then double-click on the empty value to change it.
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 + Forum. One other note: the "nuke a user" admin page and Intermedia won't run unless you set open_cursors = 500 for your database. For more information on Oracle configuration look at http://photo.net/wtr/oracle-tips.html or search the Web/db Q&A - Forum. One other note: the "nuke a user" admin page and + Forum. One other note: the "nuke a user" admin page and Intermedia won't run unless you set open_cursors = 500 - for your database.
+ ++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 ACS instance on the same drive. For the rest of these instructions, we'll assume that you used drive C:. -
+ ++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 - is called "yourdomain", is going to be at +
+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 ACS (see above) into - c:\temp\acs.tar.gz
use WinZip (or equivalent) to extract the files to - c:\web\yourdomain
+ "yourdomain.com".
+++
- +
download the ACS (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. -
+ ++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
- You most likely will see a slew of "Commit point reached . . . - " messages. This does not indicate a problem. + +
+ 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 -
- +
+ +
- +
If you have interMedia installed, while still in c:\web\yourdomain\www\doc\sql, run -
+ +
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. -
+ +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 ACS 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:
+ 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). -
++ point (you'll need to save this file with a rather than .txt + extension). +
++ ++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 - "yourservername" in the name (e.g. +
+Each section of yourdomain.ini has a hardcoded + "yourservername" in the name (e.g. [ns/server/yourservername/acs]). This means that the ACS 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 - "Yourdomain Network" owned by - "webmaster@yourdomain.com", you'll probably want to edit + 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 + "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.
+ ++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 -
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 - message "Error in serving group pages", you probably forgot to +
+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:
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. -
+ +Now, you need to protect the proper administration directories of the ACS. 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
+ +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 yourself as as member of the site-wide administration group. Start by logging out as yourself and logging in as the system user (email of - "system"). Change the system user's password. Visit the + "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'; -+- The ACS ships with a user named "anonymous" (email - "anonymous") to serve as a content owner. If you're + +
+ +++ The ACS 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 user's password. In recent versions of the ACS you cannot log into - "anonymous" because the account does not have a valid user + "anonymous" because the account does not have a valid user state. Log in as a sysadmin and change the anonymous user's password from https://yourservername/admin/users. You should read the documentation for user registration and access control and decide what the appropriate user state is for anonymous on your site. -
+ ++A few pointers: -
++ ++Run the acceptance tests in /doc/acceptance-test -
+ +You can run multiple instances of the ACS on a physical machine but they must each be set up as a separate Windows service. Each instance of the ACS 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 - ACS 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 + ACS 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: -
For each of these tablespaces/users you would load the ACS 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 ACS 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 @@ -238,11 +446,43 @@ 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$)($Id$)+@@ -22,7 +22,7 @@ Overview - One of ACS'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 ACS. Our goal is to develop a coherent API for database access which - makes this even easier. + 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. The Old Way - Here's a typical block of code from an ACS 3.x dynamic page: + Here's a typical block of code from an OpenACS 3.x dynamic page: @@ -153,15 +153,18 @@ - 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. + The new commanddb_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.@@ -188,7 +191,6 @@ - The new command db_foreach writes our old while loop for us. + The new commanddb_foreach writes + our old while loop for us.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 @@ -501,7 +503,7 @@ Therefore, the Database Access API provides a database-independent way to represent + empty string):null (instead of the Oracle-specific idiom of the - empty string):. db_null db_null .Use it instead of the empty string whenever you want to set a column value explicitly to @@ -584,17 +586,15 @@null , e.g.:- - - db_abort_transaction - db_abort_transaction +db_abort_transactionAborts all levels of a transaction. That is if this is called within @@ -608,17 +608,17 @@ - + +- db_null - + db_null db_null @@ -633,16 +633,16 @@ - + +- db_foreach - @@ -684,16 +684,16 @@db_foreach statement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ +db_foreachstatement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ [ -column_arrayarray_name | -column_setset_name ] \code_block [ if_no_rowsif_no_rows_block ] - + +- db_1row - @@ -719,16 +719,16 @@db_1row statement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ +db_1rowstatement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ [ -column_arrayarray_name | -column_setset_name ]- + +- db_0or1row - @@ -744,11 +744,11 @@db_0or1row statement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ +db_0or1rowstatement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ [ -column_arrayarray_name | -column_setset_name ]- + db_nextval db_nextval - db_nextval sequence-name +db_nextvalsequence-name @@ -764,17 +764,17 @@ - + +- db_register_pooled_sequence - db_register_pooled_sequence sequence-name pool-size +db_register_pooled_sequencesequence-name pool-size Registers the sequence sequence-name to be pooled, with a pool @@ -786,11 +786,11 @@- + db_string db_string - db_string statement-name sql [ -defaultdefault ] [ -bindbind_set_id | -bindbind_value_list ] +db_stringstatement-name sql [ -defaultdefault ] [ -bindbind_set_id | -bindbind_value_list ]Returns the first column of the result of SQL query @@ -808,11 +808,11 @@ - + db_list db_list - db_list statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_liststatement-name sql [ -bindbind_set_id | -bindbind_value_list ]Returns a Tcl list of the values in the first column of the result of SQL @@ -827,11 +827,11 @@ - + db_list_of_lists db_list_of_lists - db_list_of_lists statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_list_of_listsstatement-name sql [ -bindbind_set_id | -bindbind_value_list ]Returns a Tcl list, each element of which is a list of all column values @@ -844,11 +844,11 @@ - + db_dml db_dml - db_dml statement-name sql \ +db_dmlstatement-name sql \ [ -bindbind_set_id | -bindbind_value_list ] \ [ -blobsblob_list | -clobsclob_list | -blob_filesblob_file_list | -clob_filesclob_file_list ] @@ -892,18 +892,18 @@- , - db_write_clob , - db_write_blob + db_blob_get_file , + db_write_clob , + db_write_blob db_blob_get_file - db_write_clob statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_write_clobstatement-name sql [ -bindbind_set_id | -bindbind_value_list ] -db_write_blob statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_write_blobstatement-name sql [ -bindbind_set_id | -bindbind_value_list ] -db_blob_get_file statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_blob_get_filestatement-name sql [ -bindbind_set_id | -bindbind_value_list ]Analagous to ns_ora write_clob/write_blob/blob_get_file . @@ -914,10 +914,10 @@- + db_release_unused_handles db_release_unused_handles - db_release_unused_handles + db_release_unused_handlesReleases any allocated, unused database handles. @@ -926,11 +926,11 @@- + db_transaction db_transaction - db_transaction code_block [ on_error {code_block } ] +db_transactioncode_block [ on_error {code_block } ]Executes transactionally. Nested @@ -981,12 +981,12 @@ code_block - + db_resultrows db_resultrows - db_resultrows +db_resultrowsReturns the number of rows affected or returned by the previous @@ -997,10 +997,10 @@ - + db_with_handle db_with_handle - @@ -1037,20 +1037,20 @@db_with_handle var code_block +db_with_handlevar code_block - + +- db_nullify_empty_string - db_nullify_empty_string string +db_nullify_empty_stringstring For true SQL purists, we provide the convenience function - @@ -1088,134 +1088,7 @@, which returns + db_nullify_empty_string db_nullify_empty_string , which returns [db_null] if itsargument is the empty string and can be used to encapsulate another Oracle quirk: string - Implementation Design (work in progress) - - -The ideas here are preliminary, so please send feedback to -michael@arsdigita.com . There may well - be a much simpler, superior design that I (Michael) am just missing right - now. If so, please let me know!The basic idea is to translate the logical - - -into an actual SQL statement, written in - the appropriate SQL dialect for the RDBMS that is in use. The - statement-name argument is essentially a convenience that enables - the SQL for the "default dialect" to be written inline. For 3.4, we - will probably use configuration parameters to tell the Database Access API - what the default dialect is and what dialect is actually in use: sql - -[ns/server/ - -server_name /acs] -... -DefaultSQLDialect=oracle8 -SQLDialect=postgres7 - -- (An alternative approach would be to use the ACS Package Manager, i.e., - install a "pseudo-package" with no actual code to indicate what - RDBMS is installed. Then, the Database Access API could query the APM to - figure what SQL dialect to employ.) - - -For instructing the Database Access API to translate a named statement in - a specific SQL dialect, we may define a new API call: - -- - -statement_location statement_name sql_dialect sql - -- which would be called at server initialization time. The Database Access API - will then know to use the SQL statement appropriate for the specified - - -SQLDialect . (The namedb_implement_statement is - very tentative.)Issues: - -- - -- - -- Is making the caller of -db_implement_statement explicitly - specify the statement location (e.g., "/bboard/q-and-a") too much - of a pain? Can we make this more convenient somehow? -- -- In the case that the inline SQL is not in the specified - -SQLDialect , reading the rewritten SQL into memory for the life - of the server may not be a good idea. The three basic approaches I can think - of to implement the -db_implement_statement API are: -- -- - -- Cache the rewritten SQL for the appropriate SQL dialect in an - -nsv array -- -Cache the rewritten SQL for the appropriate SQL dialect in a special - database table that we keep pinned in memory - -- -- Cache the rewritten SQL for the appropriate SQL dialect in a special - file, maybe even a DBM file - -- - -- Given the above two issues, should we rethink the - - -db_implement_statement API - altogether? -- One possibility is a file-based approach, where the alternative SQL - statements would live in conventionally named and located files, e.g., - - -/bboard/q-and-a.postgres7 would contain Postgres 7 versions of - the SQL statements in/bboard/q-and-a.tcl .) A potential con of - this approach is that the Database Access API would have to perform file I/O - for every SQL statement that's been rewritten. This may be a non-issue; I - don't actually know. (We could augment this approach with caching too, - perhaps a fixed-size LRU cache.)Another similar approach would be just to have one massive, magic file for - each SQL dialect that maps each statement identifier (location plus name) to - the corresponding statement. - -- Another larger problem is the fact that this design does not work for - instances where we build a SQL statement based on control flow logic, e.g., - we sometimes join in an extra table based on the user input. This problem - doesn't mean that the design as a whole is broken; it just means that - this design alone does not get us all the way to full SQL abstraction. - Version 2.1 of - -the ArsDigita Oracle - Driver adds a set ofns_ora analogs for the following -ns_db calls: -0or1row ,1row , -select , and -dml . - (It also addsns_ora - array_dml .) Thus, the groundwork for implementing the above API for - ACS/Oracle is already established.Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -7,7 +7,7 @@ - ($Id$) One of the major design features of ACS 4 is the explicit representation + One of the major design features of OpenACS 4 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 Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -1,5 +1,5 @@- ACS 4 Data Models and the Object System +OpenACS 4 Data Models and the Object System By @@ -8,8 +8,8 @@Pete Su Overview -Developing data models in ACS 4 is much like developing data models -for ACS 3, save for the implementation. As usual, you need to examine +Developing data models in OpenACS 4 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 @@ -49,12 +49,12 @@ -In ACS 4, the key to enabling these types of services on your +In OpenACS 4, 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 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 ACS 4, or that may be reusable in +managed by any central service in OpenACS 4, or that may be reusable in the context of future applications. Every object in the system is represented using a row in the @@ -192,7 +192,7 @@acs_objects table. This table defines all the standard attributes that are stored on every @@ -100,7 +100,7 @@ newobject type . Object types are analogous to classes in programming languages such as C++ and Java. For example, in Java a class defines a set of attributes that store data and a set of methods -that run code. In ACS 4, we use one or more Oracle tables to store the +that run code. In OpenACS 4, 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.-We can stop here and not bother to register the usual ACS 3.x +We can stop here and not bother to register the usual OpenACS 3.x attributes of @@ -416,7 +416,7 @@creation_user ,creation_date andlast_modified , since the object typeacs_object already defines these attributes. Again, @@ -282,12 +282,12 @@ 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 -that's not stored directly in the table you defined. The ACS 4 Object +that's not stored directly in the table you defined. The OpenACS 4 Object System defines these attributes on the typeacs_object since all objects should have these attributes. Internally, there are tables that store this information for you. Most of the data is pretty self-explanatory and reflects attributes that existed in the earlier -ACS 3.x data models, with the exception of thecontext_id +OpenACS 3.x data models, with the exception of thecontext_id attribute.-Anything in your data model that needs to be available to general ACS +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 @@ -440,12 +440,12 @@In this section we cover some overall guidelines for designing data -models that are meant to be integrated with the ACS object +models that are meant to be integrated with the OpenACS object system. -There are two basic rules you should follow when designing ACS 4 data +There are two basic rules you should follow when designing OpenACS 4 data models: @@ -480,9 +480,9 @@ The reason behind these two rules is pretty straightforward: First, -the ACS Object system itself is meant to be a generic and reusable +the OpenACS Object system itself is meant to be a generic and reusable tool for any application to use for basic services. Second, in order -for this to work, the various parts of the ACS Objects data model must +for this to work, the various parts of the OpenACS Objects data model must be interpreted in the same way by all applications that use the data model. Therefore, assigning any application-specific semantics to any part of the core data model is a bad thing to do, because then the @@ -516,7 +516,7 @@ Summary -Hooking into the ACS 4 object system brings the application developer +Hooking into the OpenACS 4 object system brings the application developer numerous benefits, and doing it involves only four easy steps: Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml 24 Dec 2001 19:31:43 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -33,30 +33,30 @@ - ROOT/ -bin/ -parameters/ +ROOT/ + bin/ + parameters/ ad.ini -tcl/ + tcl/ core tcl libraries here -www/ -admin/ -bboard/ + www/ + admin/ + bboard/ site wide admin for bboard -intranet/ + intranet/ site wide admin for intranet ... and so on for all modules ... -bboard/ + bboard/ pages for bboard -admin/ + admin/ other admin pages for bboard -intranet/ + intranet/ pages for bboard -admin/ + admin/ other admin pages for intranet -doc/ + doc/ documentation sql/ core and application data models here @@ -94,41 +94,41 @@- @@ -231,53 +231,53 @@ROOT/ -bin/ -packages/ -acs-admin/ -acs-api-browser/ -acs-content-repository/ -acs-core-docs/ -acs-developer-support/ -acs-kernel/ -acs-ldap-authentication/ -acs-messaging/ -acs-subsite/ -acs-templating/ -acs-test-harness/ -acs-util/ -acs-workflow/ -bboard/ +ROOT/ + bin/ + packages/ + acs-admin/ + acs-api-browser/ + acs-content-repository/ + acs-core-docs/ + acs-developer-support/ + acs-kernel/ + acs-ldap-authentication/ + acs-messaging/ + acs-subsite/ + acs-templating/ + acs-test-harness/ + acs-util/ + acs-workflow/ + bboard/ bboard.info -sql/ + sql/ data model -tcl/ + tcl/ tcl library code -www/ -admin/ + www/ + admin/ administration pages other pages -doc/ + doc/ documentation -message-catalog/ -news/ -notification/ -page/ -tcl/ + message-catalog/ + news/ + notification/ + page/ + tcl/ bootstrap code -www/ + www/ misc pages- @@ -291,12 +291,14 @@ROOT / - +-- packages/APM Root +ROOT/ + +-- packages/ APM Root | - +-- notes/Package Root + +-- notes/ Package Root | | | | | +-- sql/ | | | | | +-- oracle/ | | | | - | | | +-- notes-create.sqlData Model Creation Script for Oracle - | | | +-- notes-drop.sqlData Model Drop Script - | | | +-- *.sqlData Model Files + | | | +-- notes-create.sql Data Model Creation Script for Oracle + | | | +-- notes-drop.sql Data Model Drop Script + | | | +-- *.sql Data Model Files | | +-- postgresql/ | | | | - | | | +-- notes-create.sqlData Model Creation Script for PostgreSQL - | | | +-- notes-drop.sqlData Model Drop Script - | | | +-- *.sqlData Model Files + | | | +-- notes-create.sql Data Model Creation Script for PostgreSQL + | | | +-- notes-drop.sql Data Model Drop Script + | | | +-- *.sql Data Model Files | +-- tcl/ | | | - | | +-- notes-procs.tclTcl Library - | | +-- notes-procs.xqlSQL92 Queries for notes-procs.tcl - | | +-- notes-procs-oracle.xqlOracle-specific queries for notes-procs.tcl - | | +-- notes-procs-postgresql.xqlPostgreSQL-specific Queries for notes-procs.tcl - | | +-- notes-init.tclTcl Initialization - | | +-- notes-init.xqlQueries for notes-init.tcl (work in all DBs) - | | +-- *.tclTcl Library Files + | | +-- 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/ | | | - | | +-- admin/Administration UI - | | | +-- tests/Regression Tests - | | | | +-- index.tclRegression Test Index Page - | | | | +-- ...Regression Tests - | | | +-- index.tclAdministration UI Index Page - | | | +-- ...Administration UI Pages + | | +-- admin/ Administration UI + | | | +-- tests/ Regression Tests + | | | | +-- index.tcl Regression Test Index Page + | | | | +-- ... Regression Tests + | | | +-- index.tcl Administration UI Index Page + | | | +-- ... Administration UI Pages | | | - | | +-- doc/Documentation - | | | +-- index.tclDocumentation Index Page - | | | +-- ...Administration Pages - | | +-- index.tclUI Index Page - | | +-- index.adpUI Index Template - | | +-- index.xqlQueries for UI Index page - | | +-- *.tclUI Logic Scripts - | | +-- *.adpUI Templates - | | +-- *-oracle.xqlOracle-specific Queries - | | +-- *-postgresql.xqlPostgreSQL-specific Queries - | +-- notes.infoPackage Specification File + | | +-- doc/ Documentation + | | | +-- index.tcl Documentation Index Page + | | | +-- ... Administration Pages + | | +-- index.tcl UI Index Page + | | +-- index.adp UI Index Template + | | +-- index.xql Queries for UI Index page + | | +-- *.tcl UI Logic Scripts + | | +-- *.adp UI Templates + | | +-- *-oracle.xql Oracle-specific Queries + | | +-- *-postgresql.xql PostgreSQL-specific Queries + | +-- notes.info Package Specification File +-- Other package directories.- + -
+ +- File Type - Its Use + Naming Convention File Type +Its Use +Naming Convention |
Data Model Creation Script @@ -605,7 +607,7 @@ - Click the button Create Package . +@@ -625,10 +627,10 @@ data model. Click the button "Create Package". 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 calledManage file information , - then theScan the link on that page to scan the + 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 thepackages/notes directory for - additional files in this packagepackages/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 thenotes package. @@ -644,8 +646,8 @@+ If your package has parameters, create them using the "Manage + Parameter Information" link. Now go back to the main management page for the notes - If your package has parameters, create them using theManage - Parameter Information link.The new package has been created and installed in the server. At this point, you should add your package files to your CVS repository. @@ -736,7 +738,7 @@ the Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -1,5 +1,5 @@ -Site Map page, which is by default available at/acs-admin/site-map . Use the interface here to add a new sub-folder callednotes to - the root of the site, then clicknew application to mount a new + the root of the site, then click "new application" to mount a new instance of thenotes application to the site. Name the new instancenotes-1 .- Parties in ACS 4 ++ Parties in OpenACS 4 by +supertype is called a "party". -Rafael H. Schloming @@ -18,13 +18,13 @@ 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 aparty .A classic example use of the @@ -34,12 +34,12 @@ -party supertype is evident +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 +isn't a company. It is a "party".party .Most developers who do significant work with the ACS will become + 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 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 @@ -71,7 +71,7 @@ row in the groups table represents the most basic form of an aggregation of individuals that is represented. -+ Persons 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 @@ -98,7 +98,7 @@ - + Users 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 @@ -112,8 +112,8 @@ 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 ACS 4 data model references the persons or -parties table, @@ -152,7 +152,7 @@ -not the users table. If this feature is +because wherever possible the OpenACS 4 data model references the persons or +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.+ Groups 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 @@ -177,11 +177,11 @@ - + Group Relations 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 +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 @@ -192,14 +192,14 @@ 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 arecomponents of +situation the U.S. and European divisions are "components" of the company, i.e., membershipis 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 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 @@ -257,7 +257,7 @@ - + Group Composition Group Composition Composition relations can be created or destroyed using the composition_rel package. The only restriction on compositions is that there @@ -434,7 +434,7 @@ the parties data model in a number of ways. This section will describe some of the more common ways. -+ Specializing Users 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 @@ -448,7 +448,7 @@ users, persons, parties, and acs_objects tables. This child table could then store any extra information relevant to the MENSA community. -+ Specializing Groups Specializing Groups If one were to build an intranet application on top of the 4.0 party system, it is likely that one would want to take advantage of the systems @@ -457,7 +457,7 @@ 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 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. Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml 24 Dec 2001 19:31:43 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -13,7 +13,7 @@ -The ACS 4 Permissions system allows developers and administrators to +The OpenACS 4 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 @@ -26,7 +26,7 @@ Although this may all sound easy and wonderful, no developer or administrator would want toexplicitly set access control rights forevery user andevery object on a -site. Therefore, ACS 4 has two auxiliary mechanisms for making this +site. Therefore, OpenACS 4 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 ofobject context , which allows applications to group objects @@ -43,11 +43,11 @@-In ACS 3.x, the groups system allowed developers and administrators to +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 ACS 4 object type system, +contained a meta-data system much like the OpenACS 4 object type system, but that's not relevant right now.) @@ -64,7 +64,7 @@-In ACS 3.x, you also could not express the fact that group A should +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 in the real world, though not as often. A good example is an @@ -75,7 +75,7 @@ -ACS 4 solves both of these modeling problems by introducing a new +OpenACS 4 solves both of these modeling problems by introducing a new 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 theparties @@ -122,7 +122,7 @@The users table is also defined in this data model as a subtype ofperson . It contains many of the basic columns -that the old ACS 3.xusers table contained. +that the old OpenACS 3.xusers table contained.@@ -169,18 +169,18 @@ -In ACS 4, a privilege models the right to perform some operation on +In OpenACS 4, 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 implement access control by granting users some combination of -read. write or execute privileges on files and directories. In ACS 4, +read. write or execute privileges on files and directories. In OpenACS 4, the table of privileges is organized hierarchically so that developers can define privileges that aggregate some set of privileges together. For example, if we have read, write, create and delete privileges, it might be convenient to combine them into a new privilege called "admin". Then if we grant a user this privilege she is automatically granted all the child privileges that the privilege -contains. The ACS 4 kernel data model actually defines these +contains. The OpenACS 4 kernel data model actually defines these privileges as follows: @@ -239,25 +239,27 @@-In ACS 4, an object context is a generalization of the scoping -mechanism introduced in ACS 3.x. "Scoping" and "scope" are terms best +In OpenACS 4, 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 + scope + user_id group_id ... |
... user @@ -298,7 +300,7 @@ 123 -In ACS 4, rather than breaking the world into a limited set of scopes, +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 another object that represents the security domain to which the object belongs. By convention, if an object A doesn't have any permissions @@ -317,7 +319,7 @@ 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 -privileges whenever we create a message, which is tedious. In ACS 4, +privileges whenever we create a message, which is tedious. In OpenACS 4, a reasonable thing to do is to create an object representing a forum, and point thecontext_id field of a new message at the forum. Then, suppose we grant every user in the system read-access to @@ -341,7 +343,7 @@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 ACS +are "magic" in some sense because they are created by default by OpenACS for a specific purpose. The object default_context represents the root of the context hierarchy for the entire site. All permission searches walk up the tree to this point and then stop. If @@ -502,7 +504,7 @@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 @@ -527,7 +529,7 @@if tag is something that the ACS 4 template system +Theif tag is something that the OpenACS 4 template system defines for you to support conditional presentation. Thetemplates developer guide provides more information about this.-ACS 4 defines three separate mechanisms for specifying access control +OpenACS 4 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, Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -15,14 +15,14 @@ - - : As you'd expect, there is + Server -global- 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(which supersedes nsv APIns_share from the pre-3.0 API).- : Each Tcl script (ADP, Tcl page, + Script -global- 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 @@ -64,9 +64,9 @@ 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 -switchThe moral: if you have a lightweight scheduled procedure +which runs frequently, don't use the @@ -128,11 +128,11 @@ more than one value from a function. When to use which depends on the circumstances.-thread +switch.+ Using Arrays and Pass-By-Value Using Arrays and Pass-By-Value -The one we generally prefer is @@ -172,7 +172,7 @@ -returning an . It has all the nice properties of +The one we generally prefer is returning an-formatted list array -get -formatted list. It has all the nice properties of pass-by-value, and it uses Tcl arrays, which have good native support. array +get + Using Arrays and Pass-By-Reference Using Arrays and Pass-By-Reference Sometimes pass-by-value incurs too much overhead, and you'd rather @@ -189,8 +189,8 @@ almost not at all on the size of the entries. -You implement pass-by-reference in Tcl by @@ -221,17 +221,17 @@taking the name of an array -as an argument and . +You implement pass-by-reference in Tcl by taking the name of an array +as an argument andupvar itupvar it.upvar s through several layers of the call stack, you'll have a hard time debugging.+ Multisets: Using ns_set s and Pass-By-ReferenceMultisets: Using ns_set s and Pass-By-ReferenceAn 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 amultiset orbag .If your data can have multiple entries with the same key , -you should use the AOLserver built-in. You can also do a case-insensitive lookup on an + -ns_set If your data can have multiple entries with the same key, +you should use the AOLserver built-in Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -9,7 +9,7 @@. You can also do a case-insensitive lookup on an +ns_set 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.Overview -This document is a brief introduction to the ACS 4 Request Processor; +This document is a brief introduction to the OpenACS 4 Request Processor; more details can be found in the @@ -18,14 +18,14 @@. Here we cover the high level concepts behind the system, and implications and usage for the application developer. The Old Way -In older versions of the ACS, the mapping between URLs and pages was -simple. AOLserver (the usual webserver for the ACS) would find the +In older versions of the OpenACS, the mapping between URLs and pages was +simple. AOLserver (the usual webserver for the OpenACS) would find the appropriate file by appending the server's page-root to the path in 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 the server to look in the filesystem for @@ -107,7 +107,7 @@/web/foo-service/www/bar.html , and return that file. -This was simple enough, but ACS did not provide a clean centralized +This was simple enough, but OpenACS did not provide a clean centralized mechanism for the following requirements of larger web services: @@ -39,10 +39,10 @@ -To achieve this functionality above in ACS 3.x, developers used an ad +To achieve this functionality above in OpenACS 3.x, developers used an ad hoc combination of AOLserver filters, thens_perm call, -special purpose code in pages, and other procedures. In ACS 4, the -Request Processor, along with the ACS Package Manager, centralizes and +special purpose code in pages, and other procedures. In OpenACS 4, the +Request Processor, along with the OpenACS Package Manager, centralizes and unifies this functionality, making it more transparent and readily available to developers.Next, the Request Processor checks if the user has appropriate access -privileges to the requested part of the site. In ACS 4, access control +privileges to the requested part of the site. In OpenACS 4, access control is dictated by the permissions system . In this case, the RP checks if the user has "read" priviledges on the object in the site map specified by the URL. This object is typically Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -1,5 +1,5 @@- Writing ACS 4 Application Pages +Writing OpenACS 4 Application Pages @@ -18,10 +18,10 @@ 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 ACS 4. First, we'll talk about the code needed to make +development in OpenACS 4. First, we'll talk about the code needed to make your pages aware of which application instance they are running in. Second, we'll talk about using the form builder to develop -form-based user interfaces in ACS 4. While these seem like unrelated +form-based user interfaces in OpenACS 4. 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. @@ -34,7 +34,7 @@As you will recall from the packages tutorial, the Request -Processor (RP) and Package Manager (APM) in ACS 4 allow site +Processor (RP) and Package Manager (APM) in OpenACS 4 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 @@ -293,7 +293,7 @@ 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 ACS: +reflect the typical logic of a forms based page in OpenACS:@@ -395,7 +395,7 @@ -This is a good example of the leverage available in the ACS 4 +This is a good example of the leverage available in the OpenACS 4 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, @@ -411,7 +411,7 @@ -In ACS 4, application pages and scripts can be aware of the package +In OpenACS 4, 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. Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -1,5 +1,5 @@ - Using Templates in ACS 4 +Using Templates in OpenACS 4 @@ -11,7 +11,7 @@ -The ACS 4 Template System (ATS) is designed to allow developers to +The OpenACS 4 Template System (ATS) is designed to allow developers to cleanly separate application logic fromdisplay logic . The intent is to have all of the logic related to manipulating the database and other application state data in one @@ -34,7 +34,7 @@-In the overall context of our example ACS Notes application, this +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 @@ -75,7 +75,7 @@ ad_page_contract { - Form to add a note in ACS Notes. + Form to add a note in OpenACS Notes. @author Jane Coder @creation-date 11 Oct 2000 @@ -123,7 +123,7 @@ string value. Later on, we'll see how to use more powerful kinds of data sources for representing multiple rows from an SQL query. You also include overall documentation for the page in the contract, and -ACS has automatic tools that extract this documentation and make it +OpenACS has automatic tools that extract this documentation and make it browsable. @@ -223,7 +223,7 @@ 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 ACS 4, the +queries and application logic, and another for display. In OpenACS 4, the logic part of the page is just a .tcl that sets updata sources that are used by the display part of the page. The display part of the page is an.adp file with some Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -43,11 +43,13 @@- + -
+ +- Constraint type + Abbreviation Constraint type +Abbreviation |
references (foreign key) fk @@ -97,7 +99,7 @@ entire data model :) -+ Notes: Notes: Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -6,7 +6,7 @@ If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints -ACS version numbers help identify at a high-level what is in a +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: @@ -17,9 +17,9 @@A change in the major version number indicates a fundamental -change in the architecture of the system, e.g. ACS 2 to ACS 3. A +change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A change in theminor version number signifies the addition of -new modules and minor data model changes, e.g. ACS 3.1 to ACS 3.2. +new modules and minor data model changes, e.g. OpenACS 3.1 to OpenACS 3.2. The finalrelease number indicates the relative maturity of a release and marks things like bug fixes; it follows the ordered progression: @@ -41,13 +41,13 @@-acs-3.2.2 -acs-4.0.beta +openacs-3.2.5 +openacs-4.0.beta -The first is a relatively mature release of the ACS 3.2 base code -and the second is a non-public release of ACS 4.0 that probably still +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. @@ -96,7 +96,7 @@-In the future, ArsDigita packages should follow this same +In the future, OpenACS packages should follow this same convention on version numbers. @@ -107,11 +107,11 @@So what distinguishes an alpha release from abeta release? Or from a production release? We follow a specific set of -rules for how ACS makes the transition from one state of maturity to +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 -installs and cleanly upgrades from the previous version of ACS. In +installs and cleanly upgrades from the previous version of OpenACS. In addition to this the release label implies:Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -285,7 +285,7 @@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 offlags +etc.) uses a colon (:) followed by any number of flags separated by commas (,), e.g.foo:integer,multiple,trim . In particular,multiple andarray are the flags that correspond to the old Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -10,12 +10,12 @@- Like any other part of the ACS, PL/SQL 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: + 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: @@ -139,7 +139,7 @@ . delete from parties - where party_id = myproc .party_id; + where party_id = myproc.party_id; . . end myproc; Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml 24 Dec 2001 19:31:43 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -31,11 +31,11 @@ things you can do:- @@ -134,7 +134,7 @@On Linux: Get the+ - On Linux: Get the psgml rpm fromRedHat's docbook-tools and install it as usual.On other systems: Get the tarball from thePSGML Website. +On other systems: Get the tarball from the PSGML Website. Unpack it and follow the install instructions.- What is a <phrase><computeroutput>DOCTYPE</computeroutput></phrase> ? +What is a <computeroutput>DOCTYPE</computeroutput> ? All SGML and XML documents that should conform to a DTD have to declare a @@ -176,12 +176,14 @@ - + -
+ +- Key + Command Key +Command |
C-c C-e Insert an element. Uses completion and only lets you insert elements that Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -1,265 +1,238 @@ - - - - Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 1 Feb 2002 17:09:12 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,5 +1,5 @@ -ACS 4.2-beta Release Notes +OpenACS 4.2-beta Release Notes -+ -by Jeff Teeters -- + by Don Baccus and +Vinod Kurup +-This is the 4.2 beta release of the ArsDigita Community -System (ACS). The previous release was 4.1.1. -This release fixes a number of bugs -and has some enhancements. -For a complete list of bugs -fixed in 4.2-beta, please visit +-the SDM page for 4.2-beta (also called 4.2b). -+ This is a beta release of OpenACS 4.2. 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. + --Note: In this and subsequent releases, the version numbers of packages will -*not* necessarily be correlated with the ACS release number. -The release number of a package will be increased only in proportion to how -significant the changes made to that package are. For example, -in this release the acs-subsite package version -is increased from 4.1 to 4.2 because significant changes were made. -On the other hand, a package as acs-messaging brings -only minor changes to this release and is therefore only labeled 4.1.1 (from 4.1). - ++ Please report bugs using our + -+ Software Development Manager at theOpenACS website . The latest + information on installating this alpha release under Oracle 8.1.6/7 + or PostgreSQL 7.1.* can be found there as well. Currently the + toolkit will not install under Oracle 9i due to Oracle having made + "delete" an illegal name for PL/SQL procedures and functions. +-Similarly, the version of the ACS release will be increased according to -the quantity and significance of the changes made. -This release is designated as 4.2-beta because of there were significant -changes made since the previous (4.1.1) release. - ++ You may want to begin by reading our installation documentation for -or . Note that the Windows + documentation is not current for OpenACS4. + - +Features in ACS 4.2-beta. ++ After installation, the full documentation set can be found by visiting + http://[your-host]/doc. Not all pieces are updated for OpenACS 4 at + this moment. + -- -+ Enhanced subsite support. -This release scopes parties to -individual subsites, rather than the entire site. -+ -Site Wide Searching -+ Improved group support. -Group administration pages have -been made more general. They now can be used to administer parties (and persons) -rather than just groups. Group types now include a default join policy -('open', 'closed', or 'needs approval'). The group administration -pages have been made much faster. -+ 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 Edition + and OpenACS 4 now defaults to being loadable in SE. Just grep for + 'sync' to find the code. + -+ Improved permissions. -Permissions also now take into account the status of -a member in a group (e.g. whether the membership is approved) when determining -the permissions for the member. -A new view -was added (ALL_OBJECT_PARTY_PRIVILEGE_MAP) which can greatly reduce the time -required to do permission checks. It is described in file -asc-packages/acs-kernel/sql/acs-permissions-create.sql. -+ 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'. + -+ Improved documentation. -+ 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, +. As with the Oracle version, there + are steps you must take manually in order to get this feature + working. + + Bug fixes. -See --SDM for 4.2-beta -for a list. -+ 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. + -- +Package: Site-wide-search +Test Coverage: Minimal +Suggested Status: Release w/caution +Comments: -Individual package details for ACS 4.2-beta. ++ Summarised Testing Status - +Skin +Minimal +Release w/caution +Comments: - +Package: File Storage +Test Coverage: Minimal +Suggested Status: Release w/caution +Comments: -+Package: Page +Test Coverage: Minimal +Release w/caution +Comments: - ACS Kernel. -Release number increased from 4.1.1 to 4.2. Enhanced -group support, ALL_OBJECT_PARTY_PRIVILEGE_MAP view, -numerous other minor changes/fixes. -+Package: Bboard +Test Coverage: Reasonable +Suggested Status: Alpha +Comments: - ACS Subsite. -Release number increased from 4.1 to 4.2. Scoping parties to -subsites, generalize administration pages, improved permissions. -+Package: Static Pages +Test Coverage: Minimal +Suggested Status: Release w/caution +Comments: - ACS Administration. -Release number increased from 4.1 to 4.1.1. Group related -changes. -+Package: Ticket Tracker +Test Coverage: Reasonable +Suggested Status: Alpha +Comments: Don tested personally - ACS API Browser. -Release number increased from 4.1 to 4.1.1. Minor changes. -+Package: Ticket Tracker Lite +Test Coverage: Unknown +Suggested Status: +Comments: - ACS Content. -Release number increased from 4.1 to 4.1.1. -Function new changed to procedure. -+Package: Acs-lang +Test Coverage: Reasonable +Suggested Status: Alpha +Comments: Oracle only - ACS Content Repository. -Release number increased from 4.1 to 4.1.2. -Numerous minor changes and enhancements. -+Package: Simple-survey +Test Coverage: Reasonable +Suggested Status: Alpha +Comments: - ACS Core Documentation. -Release number increased from 4.1 to 4.1.1. Documentation updated and added. -+Package: Portal +Test Coverage: Extensive +Suggested Status: Alpha +Comments: - ACS Mail. -Release number increased from 4.1 to 4.1.1. Minor changes. -+Package: Notes +Test Coverage: Extensive +Suggested Status: Alpha +Comments: - ACS Messaging. -Release number increased from 4.1 to 4.1.1. -Function new added to package. -+Package: Bookmarks +Test Coverage: Extensive +Suggested Status: Alpha +Comments: - ACS Tcl. -Release number increased from 4.1.1 to 4.1.2. -Modifications to installation and site -node related procedures. -+Package: Clickthrough +Test Coverage: Extensive +Suggested Status: Alpha +Comments: - ACS Templating. -Release number increased from 4.1 to 4.1.2. -Many changes. -+Package: Acs-mail +Test Coverage: Reasonable +Suggested Status: Release w/caution +Comments: - ACS Workflow. -Release number increased from 4.1 to 4.1.1. -Minor changes. -+Package: Acs-messaging +Test Coverage: Reasonable +Suggested Status: Release w/caution +Comments: - default-master.tcl -Default master template modified to display more information about -how to use acs and customize the site. -+Package: File manager +Test Coverage: Minimal +Suggested Status: Release w/caution +Comments: - Other packages. -Packages included with this release and which did not change from -the previous release (4.1.1) are: -ACS Notification (version 4.0), ACS Utilities (version 4.0.1) -and Page (version 4.0). The only new package is Skin (version 0.1d). -- +Package: Acs-subsite +Test Coverage: Reasonable +Suggested Status: Alpha +Comments: -Requirements. +Package: General Comments +Test Coverage: Extensive +Suggested Status: Alpha +Comments: --In order to run ACS 4.1, you must be running: - +Package: Acs-events +Test Coverage: None +Suggested Status: +Comments: Automated Testing -- +Package: Acs-util +Test Coverage: Reasonable +Suggested Status: Release w/caution +Comments: Automated Testing -+Package: Acs-datetime +Test Coverage: None +Suggested Status: +Comments: Automated Testing - AOLserver 3.2 + ad10 +Package: Acs-tcl +Test Coverage: Reasonable +Suggested Status: Release w/caution +Comments: Automated Testing - Oracle driver -2.4 +Package: Acs-templating +Test Coverage: Reasonable +Suggested Status: Release w/caution +Comments: Automated Testing - Oracle 8.1.6 or 8.1.7. - Tcl 8.3.x. -AOLserver and the Oracle driver are obtainable from +Package: Acs-Content-repository +Test Coverage: Minimal +Suggested Status: Release w/caution +Comments: Automated Testing +Package: Acs-content +Test Coverage: Minimal +Suggested Status: Release w/caution +Comments: Automated Testing +Package: Acs-kernel +Test Coverage: Reasonable +Suggested Status: Alpha +Comments: Automated Testing -http://www.arsdigita.com/download/ . -Developer versions of Oracle are available for download fromOracle Technet . A version of ACS 4.0 -that runs onPostgreSQL is under -development bythe OpenACS team . -- -Upgrade Instructions for ACS 4.2-beta. +Package: Acs-bootstrap-installer +Test Coverage: Extensive +Suggested Status: Alpha +Comments: Developers have used this extensively --Please make sure that you have fully upgraded your system to ACS 4.1.1 -before upgrading to ACS 4.2-beta. For instructions on how to upgrade to -4.1.1, please see the 4.1.1 release notes included in the 4.1.1 -distribution. In order to upgrade your server, you should: - +Package: Acs-api-browser +Test Coverage: Minimal +Suggested Status: Release w/caution +Comments: Automated Testing -+Package: Acs-workflow +Test Coverage: Minimal +Suggested Status: Release w/caution +Comments: - +Package: calendar +Test Coverage: Minimal +Suggested Status: Alpha +Comments: Don tested personally + + Stop your server. - - Obtain the ACS 4.2-beta distribution from http://www.arsdigita.com/acs-repository -and replace all the files in your ACS 4.1.1 system. If you have -customized any of the ACS 4.1.1 files, please make sure that your work -is not lost when extracting the archive. The recommended approach in -this situation is use a local cvs repository for your project, -extract the tar.gz file to a temporary directory, then do a -cvs vendor import to your repository from a the extracted files. -Another approach is to -to update your files using CVS through the public -server -:pserver:anonymous@cvs.arsdigita:/usr/local/cvsroot -using the tagacs-4-2-beta-R20010307 . -However getting the files by cvs using the -tag at arsdigita.com will not include the html documentation because the html -documentation is not stored in the arsdigita cvs repository but -instead is generated outside the repository (from xml files) when a -release is created. -For -further information on CVS, please consultCVS -and 4.0 Client Development .- - Run the content-repository upgrade script: - --sqlplus @youracsdir/packages/acs-content-repository/sql/upgrade/upgrade-4.1-4.1.2.sql - -- - Restart your server. - - Login as a System Administrator and go to - /acs-admin/apm . ClickInstall -Packages and wait for the installer to load.- - A list of packages that need to be upgraded and -enabled will appear. Click on the Next button. - - A list of data model upgrade scripts will -appear. Unclick the Data model upgrade script for ACS Content -Repository (file sql/upgrade/upgrade-4.1-4.1.2.sql). Leave the other checkboxes selected. -ClickInstall Packages and the upgrade will -proceed.- - - - Restart the ACS server. -Any feedback or comments about the ACS can be sent to - - -acs@arsdigita.com . Please report all -bugs with the ArsDigitaSoftware -Development Manager (SDM) . -+ ($Id$) - - - ($Id$) - Install AOLserver ++ Install AOLserver 3.3+ad13 Download the Distribution @@ -62,7 +62,7 @@- Download Mat's AOLServer distribution to/tmp @@ -72,8 +72,7 @@joeuser:~$ cd /tmp joeuser:/tmp$ wget -c http://uptime.openacs.org/aolserver-openacs/aolserver3.3ad13-oacs1-beta-src.tar.gz -joeuser:/tmp$ cd - +joeuser:/tmp$ cd@@ -87,8 +86,7 @@ joeuser:~$ su - Password: ********** root:~$ cd /usr/local/src -root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz - +root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz @@ -119,8 +117,7 @@ root:~# mkdir -p /web /usr/local/aolserver root:~# chown -R nsadmin.web /usr/local/aolserver /web /usr/local/src/aolserver root:~# chmod 775 /usr/local/aolserver /web -root:~# exit - +root:~# exit @@ -140,8 +137,7 @@ -joeuser:~$ su - nsadmin Password: *********** -nsadmin:~$ emacs .bash_profile - +nsadmin:~$ emacs .bash_profileAdd the first set of lines, if you're using Oracle. The 2nd set @@ -163,10 +159,9 @@ export ORACLE_TERM=vt100 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data -# For Postgres +# For PostgreSQL export PATH=$PATH:/usr/local/pgsql/bin -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib - +export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib Be absolutely certain that you have entered these lines correctly @@ -184,8 +179,7 @@ nsadmin:~$ echo $PATH ...some other directory paths...:/usr/local/pgsql/bin nsadmin:~$ echo $LD_LIBRARY_PATH -:/usr/local/pgsql/lib - +:/usr/local/pgsql/lib Note: The result should be different if you're using Oracle. @@ -223,8 +217,7 @@ nsadmin:~$ cd /usr/local/src/aolserver nsadmin:/usr/local/src/aolserver$ ./conf-clean cat: BUILD-MODULES: No such file or directory -Done. - +Done. @@ -237,16 +230,15 @@ -nsadmin:/usr/local/src/aolserver$ echo "postgresql" > conf-db - +nsadmin:/usr/local/src/aolserver$ echo "postgresql" > conf-db@@ -259,14 +251,12 @@ conf-inst should contain the location where AOLserver is to be installed. This defaults to/usr/local/aolserver , so we - don't need to change anything. + don't need to change it.-nsadmin:/usr/local/src/aolserver$ echo "make" > conf-make - +nsadmin:/usr/local/src/aolserver$ echo "make" > conf-makeCompile and install AOLserver and modules -nsadmin:/usr/local/src/aolserver$ ./conf - +nsadmin:/usr/local/src/aolserver$ ./confThis takes about 5 minutes. All of the results are logged to @@ -292,8 +282,7 @@ nsadmin:/usr/local/src/aolserver$ cd -nsadmin:~$ ./bin/nsd -t sample-config.tcl - +nsadmin:~$ ./bin/nsd -t sample-config.tclAs the AOLserver daemon starts up, you should see a few normal @@ -302,8 +291,7 @@ Warning: nsd.tcl: nsssl not loaded -- key/cert files do not exist. -Warning: nsd.tcl: nscp not loaded -- user/password is not set. - +Warning: nsd.tcl: nscp not loaded -- user/password is not set.The first warning means that the server is missing files for @@ -328,21 +316,20 @@ -nsadmin:~$ lynx localhost:8000 - +nsadmin:~$ lynx localhost:8000 -You should see a Welcome to AOLserver - page. If this doesn't work, try going to -http://127.0.0.1:8000/ . If this still doesn't - work, check out the+ You should see a "Welcome to AOLserver" page. If this + doesn't work, try going to + http://127.0.0.1:8000/ . If this + still doesn't work, check out thesection below. Shutdown the test server: -nsadmin:~$ killall nsd - +nsadmin:~$ killall nsdThe killall command will kill @@ -366,8 +353,7 @@ You should also try to find lines of the form:[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000) -[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections - +[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connectionsIf you can find these lines, try entering the URL the server is listening on. If you cannot find these lines, there must be an error @@ -380,8 +366,7 @@ -set hostname [ns_info hostname] -set address [ns_info address] - +set address [ns_info address]If you get an error that nssock can't get the requested address, you can set these manually: @@ -390,8 +375,7 @@ #set hostname [ns_info hostname] set hostname 127.0.0.1 #set address [ns_info address] -set address 127.0.0.1 - +set address 127.0.0.1If you get an error that nssock can't assign the requested port, Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml 1 Feb 2002 17:09:12 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -48,7 +48,8 @@ All questions and comments regarding this guide should be sent tovinod@kurup.com . + url="mailto:vinod@kurup.com">vinod@kurup.com or on theOpenACS bboards .Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/next-steps.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/Attic/next-steps.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/next-steps.xml 1 Feb 2002 17:14:07 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/next-steps.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -1,7 +1,7 @@ ($Id$) Next Steps -+ Backup Strategy Here are some tips from Don Baccus regarding backup strategy: @@ -56,14 +56,14 @@ 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 . +root .Download the backup script. Save the file export-oracle.txt as -/tmp/export-oracle.txt . +/tmp/export-oracle.txt @@ -73,8 +73,7 @@ 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 @@ -85,8 +84,7 @@ 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@@ -140,33 +138,31 @@ . exporting dimensions . exporting post-schema procedural objects and actions . exporting statistics -Export terminated successfully without warnings. - - +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 theEDITOR="emacs - -nw" portion with whatever editor your - prefer, such as -EDITOR=vi .+ 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 - +root:~# crontab -eNow add the following line on a line by itself -0 23 * * * /usr/sbin/export-oracle - +0 23 * * * /usr/sbin/export-oracleSave the file, exit the editor. Verify that the addition @@ -176,15 +172,14 @@ root:~# crontab -l | grep export-oracle 0 23 * * * /usr/sbin/export-oracle root:~# exit -; Logout - +; Logout If you see the line, go ahead and log out. + - Set up nightly Postgres exports @@ -235,16 +230,15 @@ nsadmin:~$ cp /tmp/acs-pgbackup-init.txt /web/birdnotes/tcl/acs-pgbackup-init.tcl -nsadmin:~$ restart-aolserver birdnotes - +nsadmin:~$ restart-aolserver birdnotesThat'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 The "vacuum" command must be run periodically to reclaim space. The @@ -263,17 +257,15 @@ Edit your crontab: -nsadmin:~$ crontab -e - +nsadmin:~$ crontab -eWe'll set vacuum up to run nightly at 1 AM. Add the following line: -0 1 * * * /usr/local/pgsql/bin/vacuumdb birdnotes - +0 1 * * * /usr/local/pgsql/bin/vacuumdb birdnotes+ @@ -48,8 +47,7 @@ root:~# exit logout joeuser:~$ su - postgres -Password: *********** - +Password: ***********- How to add a second server on a different port Starting another server is simply a matter of configuring another @@ -290,8 +282,7 @@ nsadmin:~$ cp /tmp/openacs4.tcl.txt ./ +nsadmin:~$ emacsbirdnotes-dev .tcl nsadmin:~$ chmod 660birdnotes-dev .tcl -nsadmin:~$ emacsbirdnotes-dev .tcl -birdnotes-dev .tclJust like in , you'll need to set the server parameters appropriately. Be sure to @@ -316,8 +307,7 @@ nsadmin:~$ cd /web -nsadmin:~$ cp -r birdnotes birdnotes-dev - +nsadmin:~$ cp -r birdnotes birdnotes-devOr Download the OpenACS @@ -327,8 +317,7 @@ nsadmin:~$ cd /web nsadmin:/web$ tar xzvf /tmp/alpha2.tgz -nsadmin:/web$ mv openacs-4 birdnotes-dev - +nsadmin:/web$ mv openacs-4 birdnotes-dev@@ -337,8 +326,7 @@ nsadmin:/web$ cd -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/ +nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes-dev .tcl -birdnotes-dev .tclVisit the site with a web browser (using the port that you set @@ -350,14 +338,14 @@ + Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml 1 Feb 2002 17:09:12 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -58,8 +58,7 @@- 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 +apt-get install tcl8.3-dev )@@ -374,8 +362,7 @@ 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 @@ -388,8 +375,7 @@ 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@@ -400,16 +386,14 @@ -INC = ../include -I/usr/include/tcl8.3 - +INC = ../include -I/usr/include/tcl8.3Then 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@@ -424,8 +408,7 @@ 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/ @@ -437,8 +420,7 @@ - ns_param nsfts ${bindir}/nsfts.so - + ns_param nsfts ${bindir}/nsfts.so@@ -448,8 +430,7 @@ nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cd nsadmin:~$ psql -f /web/ +nsadmin:~$ restart-aolserverbirdnotes /packages/openfts-driver/sql/postgresql/load.sqlbirdnotes -nsadmin:~$ restart-aolserverbirdnotes -birdnotes @@ -467,8 +448,7 @@ Restart your server. -nsadmin:~$ restart-aolserver +nsadmin:~$ restart-aolserverbirdnotes -birdnotes Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 1 Feb 2002 17:14:07 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -23,8 +23,7 @@ joeuser:~$ su - nsadmin Password: *********** nsadmin:~$ cd /web -nsadmin:/web$ tar xzf /tmp/alpha2.tgz - +nsadmin:/web$ tar xzf /tmp/alpha2.tgz @@ -79,25 +77,22 @@ @@ -52,8 +51,7 @@ 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 birdnotesnsadmin:~$ groups -nsadmin dba web - +nsadmin dba web If you do not see these groups, take the following action:nsadmin:~$ su - Password: ************ -root:~# usermod -g nsadmin -G dba,web nsadmin - +root:~# usermod -g nsadmin -G dba,web nsadmin If you get an error about an undefined group, then add that group manually:root:~# groupadd dba root:~# groupadd nsadmin -root:~# groupadd web - +root:~# groupadd web Make sure to logout asroot when you are finished with this step and log back in as @@ -112,16 +107,14 @@ nsadmin:~$ svrmgrl SVRMGR> connect internal -Connected. - +Connected.Determine where the system tablespaces are stored: -SVRMGR> select file_name from dba_data_files; - +SVRMGR> select file_name from dba_data_files; Example results:@@ -131,8 +124,7 @@ /ora8/m01/app/oracle/oradata/ora8/temp01.dbf /ora8/m01/app/oracle/oradata/ora8/users01.dbf /ora8/m01/app/oracle/oradata/ora8/indx01.dbf -/ora8/m01/app/oracle/oradata/ora8/drsys01.dbf - +/ora8/m01/app/oracle/oradata/ora8/drsys01.dbf@@ -166,8 +158,7 @@ root:~# chown nsadmin.web /ora8/m02/oradata/ora8 root:~# chmod 775 /ora8/m02/oradata/ora8 root:~# exit -nsadmin:~$ - +nsadmin:~$ @@ -184,8 +175,7 @@ nsadmin:~$ svrmgrl SVRMGR> connect internal; -SVRMGR> create tablespace birdnotes datafile '/ora8/m02/oradata/ora8/birdnotes 01.dbf' size 50m autoextend on default storage (pctincrease 1); - +SVRMGR> create tablespacebirdnotes datafile '/ora8/m02/oradata/ora8/birdnotes 01.dbf' size 50m autoextend on default storage (pctincrease 1);@@ -194,22 +184,21 @@ birdnotespassword as our password.- + (i.e.Write down what you specify as - . You will need this information for configuring - exports and AOLserver.service_name + Write down what you specify asservice_name (i.e.birdnotes ) anddatabase_password - (i.e.birdnotespassword ) -birdnotespassword ). You + will need this information for configuring exports and + AOLserver. +SVRMGR> create user +SVRMGR> exit;birdnotes identified bybirdnotespassword default tablespacebirdnotes temporary tablespace temp quota unlimited onbirdnotes ; SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite tobirdnotes ; SVRMGR> revoke unlimited tablespace frombirdnotes ; SVRMGR> alter userbirdnotes quota unlimited onbirdnotes ; -SVRMGR> exit; -Your table space is now ready. In case you are trying to delete a @@ -229,8 +218,7 @@ ---------- 2001-12-20 -SQL> exit - +SQL> exit You should see today's date in a format 'YYYY-MM-DD.' @@ -248,24 +236,22 @@ nsadmin:~$ cp /tmp/nsd-oracle.txt ./bin/nsd-oracle -nsadmin:~$ chmod 700 ./bin/nsd-oracle - +nsadmin:~$ chmod 700 ./bin/nsd-oracle- @@ -418,8 +399,7 @@Prepare Postgres for OpenACS ++ @@ -309,8 +294,7 @@Prepare PostgreSQL for OpenACS - Preparing Postgres is just a little bit simpler than preparing + 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 (i.e.birdnotes )nsadmin:/web$ createdb +CREATE DATABASEbirdnotes -CREATE DATABASE -Next we'll set up AOLserver so that it has the proper environment variables set before launching. Download this nsadmin:/web$ cd nsadmin:~$ cp /tmp/nsd-postgres.txt ./bin/nsd-postgres -nsadmin:~$ chmod 700 ./bin/nsd-postgres - +nsadmin:~$ chmod 700 ./bin/nsd-postgres nsadmin:~$ cp /tmp/openacs4.tcl.txt ./ +nsadmin:~$ emacsbirdnotes .tcl nsadmin:~$ chmod 660birdnotes .tcl -nsadmin:~$ emacsbirdnotes .tcl -birdnotes .tclSpecifically, you'll have set the following variables @@ -350,24 +334,22 @@ Kill any current running AOLserver processes and start a new - one. (Note, if you are using Oracle, rather than postgres, replace + one. (Note, if you are using Oracle, rather than PostgreSQL, replace nsd-postgres withnsd-oracle ):nsadmin:~$ killall nsd ; Should probably see: nsd: no process killed -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/ +nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes .tcl -birdnotes .tclAttempt to connect to the service from a web browser as you did in the section. You should specify a URL like: -http:// +http://ip_name :ip_port / -ip_name :ip_port /You should see a page that looks like -nsadmin:~$ killall nsd - +nsadmin:~$ killall nsd-Loading package .info files ... this will take a few minutes - +Loading package .info files ... this will take a few minutesThis will really take a few minutes. Have faith! Finally, @@ -460,8 +440,7 @@ -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/ +nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes .tcl -birdnotes .tcl@@ -553,8 +532,7 @@ 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 @@ -572,8 +550,7 @@ nsadmin:~$ restart-aolserver birdnotes Killing 23727 nsadmin:~$ killall nsd -nsd: no process killed - +nsd: no process killedThe number 23727 indicates the process id(s) (PIDs) of the @@ -591,8 +568,7 @@ nsadmin:~$ su - Password: ************ -root:~# emacs -nw /etc/inittab - +root:~# emacs -nw /etc/inittab@@ -601,15 +577,14 @@ nss1 is unique.-nss1:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/ +nss1:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/birdnotes .tcl -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. +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.@@ -619,8 +594,7 @@ root:~# killall nsd nsd: no process killed -root:~# /sbin/init q - +root:~# /sbin/init q@@ -652,12 +625,10 @@ @@ -630,8 +604,7 @@ root:~# restart-aolserver +Killing 23750birdnotes -Killing 23750 -@@ -692,8 +663,7 @@ Debian - root:~# apt-get install daemontools-installer root:~# build-daemontools -root:~# # answer 'yes' when asked to create symlink from /service to /var/lib/svscan - +root:~# # answer 'yes' when asked to create symlink from /service to /var/lib/svscannsadmin:~$ cd /web/birdnotes -nsadmin:/web/birdnotes$ emacs run - +nsadmin:/web/birdnotes$ emacs runCopy this text into that file: @@ -702,8 +672,7 @@ #!/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 webAs root, change the ownership of this file: @@ -713,8 +682,7 @@ 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 @@ -732,8 +700,7 @@ 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 @@ -784,8 +751,7 @@ 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/birdnotesThis command will give the web @@ -807,8 +773,7 @@ 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 - +nsadmin:~$ svc -t /web/birdnotesMost of this information comes from Tom Jackson's -SVRMGR> drop user +SVRMGR> drop userbirdnotes cascade; -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=' +SVRMGR> select username, sid, serial# from v$session where username='birdnotes '; -birdnotes ';and then -SVRMGR> alter system kill session ' +SVRMGR> alter system kill session 'sid ,serial# '; -sid ,serial# ';where -sid andserial# are replaced with the corresponding values for the open session.+ Use with caution! Use with caution! If you feel the need to delete everything related to the service, you can also issue the following:-SVRMGR> drop tablespace +SVRMGR> drop tablespacebirdnotes including contents cascade constraints; -birdnotes including contents cascade constraints; -- Deleting a Postgres tablespace ++ Deleting a PostgreSQL tablespace - Dropping a Postgres tablespace is easy. You have to stop any + 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 @@ -912,8 +873,7 @@ Then, to drop the db, just do: nsadmin:~$ dropdb +DROP DATABASEbirdnotes -DROP DATABASE -$ cd /directory/where/oracle/is -$ tar -xvf oracle81701.tar - +$ tar -xvf oracle81701.tar @@ -106,8 +105,7 @@startx -joeuser:~$ startx - +joeuser:~$ startx@@ -116,8 +114,7 @@ joeuser:~$ su - Password: *********** -root:~# - +root:~#@@ -137,8 +134,7 @@ 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 @@ -153,18 +149,17 @@ - Note: the Oracle install needs about 1 GB free - on/ora8 to install - successfully. +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@@ -181,8 +176,7 @@ joeuser:~$ su - oracle -Password: ******** - +Password: ********@@ -193,8 +187,7 @@ -oracle:~$ emacs .bash_profile - +oracle:~$ emacs .bash_profileYou may get this error trying to start emacs: @@ -206,25 +199,22 @@ 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 +localhostNow, back in the oracle terminal: oracle:~$ export DISPLAY=localhost:0.0 -oracle:~$ emacs .bash_profile - +oracle:~$ emacs .bash_profileTry this procedure anytime you get an Xlib connection refused @@ -246,8 +236,7 @@ export ORACLE_TERM=vt100 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data -umask 022 - +umask 022 Save the file by typing CTRL-X @@ -260,14 +249,13 @@ - Make sure that you do not add any lines like the - following + Make sure that you donot add + any lines like the following# NLS_LANG=american -# export NLS_LANG - +# export NLS_LANGThese lines will change the Oracle date settings and will break @@ -281,8 +269,7 @@ -oracle:~$ exit - +oracle:~$ exit@@ -296,8 +283,7 @@ oracle:~$ su - oracle -oracle:~$ env | grep ORA - +oracle:~$ env | grep ORAIf it worked, you should see: @@ -308,8 +294,7 @@ 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 @@ -333,8 +318,7 @@ 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/binIf they are not, then add them to the @@ -360,8 +344,7 @@ joeuser:~$ xhost +localhost joeuser:~$ su - oracle Password: ********** -oracle:~$ export DISPLAY=localhost:0.0 - +oracle:~$ export DISPLAY=localhost:0.0 @@ -379,8 +362,7 @@ oracle:~$ su - root root:~# mount -t iso9660 /dev/cdrom /mnt/cdrom root:~# exit -oracle:~$ cd /mnt/cdrom - +oracle:~$ cd /mnt/cdrom @@ -401,8 +382,7 @@ @@ -390,8 +372,7 @@ -oracle:~$ cd /where/oracle/Disk1 - +oracle:~$ cd /where/oracle/Disk1oracle:/where/oracle/Disk1$ ls -doc index.htm install runInstaller stage starterdb - +doc index.htm install runInstaller stage starterdbIf you don't see @@ -416,8 +396,7 @@ -oracle:/where/oracle/Disk1$ ./runInstaller - +oracle:/where/oracle/Disk1$ ./runInstallerA window will open that welcomes you to the 'Oracle Universal @@ -489,8 +468,7 @@ joueser:~$ su - -root:~# ln -s /usr/bin/awk /bin/awk - +root:~# ln -s /usr/bin/awk /bin/awk @@ -507,8 +485,7 @@ Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall. root:~# mkdir -p /usr/local/java root:~# exit -joeuser:~$ exit - +joeuser:~$ exit@@ -550,9 +527,8 @@ In addition to the defaults, make sure that "Oracle SQLJ - 8.1.6.0," "Oracle Protocol Support 8.1.6.1.0," and - "Linux Documentation 8.1.6.0.0" are also checked (they - were not in release 8.1.5). + 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and + "Linux Documentation 8.1.7.0.0" are also checked. @@ -613,6 +589,30 @@ + + + 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 @@ -629,6 +629,22 @@+ + + The next screen is "Oracle Product Support" + + ++ ++ + + TCP should be checked with "Status" listed as + Required + + + Click "Next" + The "Summary" screen in the OUI @@ -639,7 +655,7 @@@@ -679,7 +695,7 @@ Enter the full pathname of the local bin directory: [/usr/local/bin]: - - Check that "(91 products)" is in the "New + Check that "(144 products)" is in the "New Installations" section title. Press ENTER here to accept default of /usr/local/bin +Press ENTER here to accept default of /usr/local/bin Creating /etc/oratab file... @@ -691,8 +707,7 @@ 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.@@ -703,8 +718,7 @@ root:~# exit -joeuser:~$ exit - +joeuser:~$ exit@@ -731,7 +745,7 @@ Make sure the "Perform Typical installation" is - not selected. +not selected.@@ -1003,8 +1016,8 @@ @@ -907,8 +921,7 @@ joeuser:~$ su - oracle Password: ********* oracle:~$ export DISPLAY=localhost:0.0 -oracle:~$ dbassist - +oracle:~$ dbassist - Go to the " temporary " and - "rollback " tabs, and change the Size + Go to the "temporary" and + "rollback" tabs, and change the Size (upper-right text box) to150 MB. Click "Next " @@ -1071,17 +1084,15 @@-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.oraAdd the following line to the end: -nls_date_format = "YYYY-MM-DD" - +nls_date_format = "YYYY-MM-DD"@@ -1095,8 +1106,7 @@ -open_cursors = 500 - +open_cursors = 500@@ -1125,8 +1135,7 @@ 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.shIn some instances, Oracle will save the file to @@ -1174,8 +1183,7 @@ -oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql - +oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql@@ -1184,8 +1192,7 @@ -oracle:~$ sqlplus system/manager - +oracle:~$ sqlplus system/managerSQL*Plus should startup. If you get an ORA-01034: @@ -1196,8 +1203,7 @@ oracle:~$ svrmgrl SVRMGR> connect internal -SVRMGR> startup - +SVRMGR> startup@@ -1209,17 +1215,15 @@ 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 @@ -1242,8 +1246,7 @@ ---------- 2000-06-10 -SQL> - +SQL> Many people encounter an error regarding maximum @@ -1252,8 +1255,7 @@ ERROR at line 1: -ORA-01450: maximum key length (758) exceeded - +ORA-01450: maximum key length (758) exceededThis error occurs if your database block size is wrong and is @@ -1299,8 +1301,7 @@ 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@@ -1316,8 +1317,7 @@ @@ -1363,8 +1362,7 @@ 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 You will see this line. -ora8:/ora8/m01/app/oracle/product/8.1.7:N - +ora8:/ora8/m01/app/oracle/product/8.1.7:NBy the way, if you changed the service name or have multiple @@ -1337,8 +1337,7 @@ -ora8:/ora8/m01/app/oracle/product/8.1.7:Y - +ora8:/ora8/m01/app/oracle/product/8.1.7:Y@@ -1412,8 +1410,7 @@ Database opened. SQL> Disconnected -Database "ora8" warm started. - +Database "ora8" warm started. @@ -1428,8 +1425,7 @@ 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 - +oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off @@ -1490,8 +1485,7 @@ 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 Debian users: @@ -1442,8 +1438,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 - + /etc/rc5.d/S20oracle8i -> ../init.d/oracle8iTest the listener automation by running the following commands @@ -1540,8 +1534,7 @@ 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 @@ -1566,8 +1559,7 @@ SQL> exit oracle:~$ exit -root:~# - +root:~# @@ -1613,8 +1603,7 @@ RedHat users: @@ -1579,8 +1571,7 @@ 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 - +listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:offDebian users: @@ -1597,8 +1588,7 @@ /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-root:~# /sbin/shutdown -r -t 0 now - +root:~# /sbin/shutdown -r -t 0 nowLog back in and ensure that Oracle started automatically. @@ -1624,9 +1613,7 @@ joeuser:~$ su - oracle oracle:~$ sqlplus system/alexisahunk@ora8 -SQL> exit - - +SQL> exit @@ -1651,23 +1638,21 @@ To fix this, you should include the following line in - + $ORACLE_HOME/dbs/init SID .ora $ORACLE_HOME/dbs/init SID .ora or for the default case, -+ $ORACLE_HOME/dbs/initora8.ora $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 @@ -1680,8 +1665,7 @@ 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 @@ -1698,8 +1682,7 @@ -export nls_lang = american - +export nls_lang = americanSetting this environment variable will override the date @@ -1709,8 +1692,7 @@ -export nls_date_format = 'YYYY-MM-DD' - +export nls_date_format = 'YYYY-MM-DD'Log back in again. If adding the @@ -1734,8 +1716,7 @@ -oracle:~$ sqlplus system/changeme - +oracle:~$ sqlplus system/changeme@@ -1744,8 +1725,7 @@ -SQL> drop user +SQL> drop useroracle_user_name cascade; -oracle_user_name cascade;@@ -1778,9 +1757,9 @@ @@ -1755,8 +1735,7 @@ your database entirely. -SQL> drop tablespace +SQL> drop tablespacetable_space_name including contents cascade constraints; -table_space_name including contents cascade constraints;-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml 1 Feb 2002 17:14:07 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -69,8 +69,8 @@- Variable - Value + Reason Variable +Value +Reason -
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml 1 Feb 2002 17:14:07 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -1,4 +1,4 @@ -- Requirement + Reason Requirement +Reason + Install PostgreSQL 7.1.3 @@ -23,8 +23,7 @@ joeuser:~$ su - Password: *********** root:~# cd /usr/local/src -root:/usr/local/src# tar xzf /tmp/postgresql-7.1.3.tar.gz - +root:/usr/local/src# tar xzf /tmp/postgresql-7.1.3.tar.gz @@ -63,11 +61,10 @@ 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 + Logout and login again aspostgres . Use theecho command to make sure that/usr/local/pgsql/bin is now in your PATH @@ -79,8 +76,7 @@ joeuser:~$ su - postgres Password: ************ postgres:~$ echo $PATH -/usr/local/bin:/usr/bin:/bin: ... :/usr/local/pgsql/bin - +/usr/local/bin:/usr/bin:/bin: ... :/usr/local/pgsql/bin@@ -99,17 +95,15 @@ 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 allCompilation 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 @@ -119,12 +113,11 @@ postgres:/usr/local/src/postgresql-7.1.3$ make install ... -Thank you for choosing PostgreSQL, the most advanced open source database engine. - +Thank you for choosing PostgreSQL, the most advanced open source database engine.- Prepare Postgres for OpenFTS +Prepare PostgreSQL for OpenFTS OpenFTS is the module that provides full text search to OpenACS 4. We @@ -136,8 +129,7 @@ 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 - +postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make install @@ -152,11 +144,10 @@ 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 @@ -185,13 +176,12 @@ 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 - +CREATE USER- Postgres errors will be logged in + PostgreSQL errors will be logged in /usr/local/pgsql/data/server.log - @@ -245,15 +234,13 @@ 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 - +root:~# chmod 700 /etc/init.d/postgresqlTest Postgres +Test PostgreSQL Create a database and try some simple commands. The output should be as shown. @@ -224,8 +214,7 @@ mytestdb=# \q postgres:~$ dropdb mytestdb -DROP DATABASE - +DROP DATABASE Test the script root:~# /etc/init.d/postgresql stop -Stopping PostgreSQL: ok - +Stopping PostgreSQL: okIf PostgreSQL successfully stopped, then use the following @@ -274,8 +261,7 @@ root:~# /etc/init.d/postgresql start Starting PostgreSQL: ok root:~# exit -postgres:~$ exit - +postgres:~$ exit Red Hat: @@ -285,15 +271,13 @@ 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 - +root:~# chmod 700 /etc/rc.d/init.d/postgresqlTest the script root:~# /etc/rc.d/init.d/postgresql stop -Stopping PostgreSQL: ok - +Stopping PostgreSQL: okIf PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot @@ -308,8 +292,7 @@ root:~# /etc/rc.d/init.d/postgresql start Starting PostgreSQL: ok root:~# exit -postgres:~$ exit - +postgres:~$ exit @@ -375,14 +354,14 @@ SuSE: @@ -319,15 +302,13 @@ 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 - +root:~# chmod 700 /etc/rc.d/init.d/postgresqlTest the script root:~# /etc/rc.d/init.d/postgresql stop -Stopping PostgreSQL: ok - +Stopping PostgreSQL: okIf PostgreSQL successfully stopped, then use the following @@ -348,8 +329,7 @@ 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 @@ -359,8 +339,7 @@ root:/etc/rc.d/init.d # cd root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start Starting PostgreSQL: ok -root:~ # exit - +root:~ # exit - @@ -371,9 +371,9 @@ -Learn more about Postgresql +Learn more about PostgreSQL Here are some links: - Official Postgres Docs +Official PostgreSQL Docs Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml 2 Feb 2002 03:47:32 -0000 1.2 @@ -1,5 +1,5 @@ - - ACS 4 Package Manager Design ++ OpenACS 4 Package Manager Design @@ -12,7 +12,7 @@ - -+ ACS Administrator directory OpenACS Administrator directory @@ -51,7 +51,7 @@ Introduction -In general terms, a package is a unit of software that +In general terms, apackage 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 @@ -62,22 +62,22 @@- -ACS Applications: a "program or group of programs +- OpenACS Applications: a "program or group of programs designed for end users" (theWebopedia definition ); also known asmodules , for historical reasons. Examples of applications includeBboard andNews .ACS Services: the aforementioned building blocks. -Examples of services include theACS -Content Repository , theACS Templating -System , and the ACS Kernel, which includes +OpenACS Services: the aforementioned building blocks. +Examples of services include theOpenACS +Content Repository , theOpenACS Templating +System , and the OpenACS Kernel, which includes APM.An installation of the ACS includes the ACS Kernel, some services that + 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 @@ -86,14 +86,14 @@ 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 -ACS Installation. Jack User discovers Jane's forum and includes a link to +OpenACS Installation. Jack User discovers Jane's forum and includes a link to it in his subsite. As interest in Jane's forum grows, she creates a subsite specializing in providing information about View cameras. This subsite now includes several package instances beyond Bboard; it could potentially include its own Ecommerce capabilities (ala @@ -203,14 +203,14 @@Yahoo! Shopping ). This could include a knowledge management application that allows users to spread expertise about view cameras and a portal application that links to reliable camera models -and resellers. Any subsite enabled package that is added to the ACS +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.- -ACS without APM vs. with APM +OpenACS without APM vs. with APM APM itself is part of a package, the +ACS Kernel , an ACS -service that is the only mandatory component of an ACS installation.APM itself is part of a package, the @@ -220,7 +220,7 @@OpenACS Kernel , an OpenACS +service that is the only mandatory component of an OpenACS installation.Competitive Analysis -The ACS is a platform for web-based application software, and any software + 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: @@ -235,15 +235,15 @@Red Hat Linux hasthe Red Hat Package Manager (RPM) Borrowing from all of the above, ACS 3.3 introduces its own package -management system, the ACS Package Manager (APM), which consists of: +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 -"ACS packages"), including:a standard format for APM packages (also called +"OpenACS packages"), including:- - version numbering, independent of any other package and the ACS as a + version numbering, independent of any other package and the OpenACS as a whole @@ -256,7 +256,7 @@ specification of the package interface + web-based tools for package management: - web-based tools for package management: @@ -270,7 +270,7 @@ obtaining packages from a remote distribution point - configuring packages (obsoleting the monolithic ACS configuration + configuring packages (obsoleting the monolithic OpenACS configuration file) @@ -281,13 +281,13 @@ upgrading packages, without clobbering local modifications a registry of installed packages , database-backed and +- a registry of installed packages , database-backed and integrated with filesystem-based version control+ web-based tools for package development: web-based tools for package development: @@ -310,7 +310,7 @@ creating new packages locally 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 ACS application +locations and names for files and patterns, for OpenACS application development. - The processes of installing, upgrading, and using packages must be @@ -323,7 +323,7 @@ All of these requirements were met, but at the cost of development simplicity. As @@ -343,10 +343,10 @@ on an appropriate URL, and set parameters for that particular instance.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 ACS 3.3 system. However, while the +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. While this is complex, especially to a new ACS developer, the + 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 ACS +subsites across the system, and be available for distribution to other OpenACS installations without doing a monolithic upgrade or reinstall. + Authoring a Package - Authoring a Package Full instructions on how to prepare an ACS package are available in . The API here can be invoked manually by a package's data model + Full instructions on how to prepare an OpenACS package are available in @@ -398,9 +398,9 @@ -. 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 .The procedure above registers an ACS application in the APM. It creates a -new ACS object and stores information about the package, such as its name, in -the APM data model. There is an analogous procedure for ACS services, called + 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 @@ -422,7 +422,7 @@ Use the +package from the OpenACS.cascade_p only if you want to completely remove the -package from the ACS.In order to determine if a particular package exists in the system, use the register_p predicate. It returns 1 if the specified @@ -439,7 +439,7 @@ -+ Maintaining Multiple Versions of a Package 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, @@ -567,7 +567,7 @@ @@ -585,7 +585,7 @@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 ACS. +available to the OpenACS.Files associated with a version can be added and removed. The path is -relative to the @@ -693,7 +693,7 @@ -package-root which is +relative to thepackage-root which isacs-server-root/packages/package-key .+ Creating Instances of a Package 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 @@ -729,8 +729,8 @@ @@ -740,7 +740,7 @@ api_doc_id integer; begin api_doc_id := apm_service.new ( - instance_name => 'ACS API Browser', + instance_name => 'OpenACS API Browser', package_key => 'acs-api-browser', context_id => main_site_id ); @@ -764,7 +764,7 @@ -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 +example, here is how theACS API Documentation service -makes itself available on the ACS main site:OpenACS API Documentation service +makes itself available on the OpenACS main site:+ Specifying Configuration Parameters for each Instance 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 @@ -872,8 +872,8 @@The central piece of the data model is the @@ -952,8 +952,8 @@apm_package_types table where each package is registered. When a new application or service is -installed on an ACS instance, a corresponding row in this table is inserted -with information about the type of package, e.g. if thebboard package is installed on your ACS server, a row +installed on an OpenACS instance, a corresponding row in this table is inserted +with information about the type of package, e.g. if thebboard package is installed on your OpenACS server, a row inapm_package_types will be created, noting that it's an application package type.The @@ -970,7 +970,7 @@ need to be tweaked for Windows compatibility.APM's user interface is part of the -ACS Administration Service . The UI is the primary -point of contact with APM by developers and administrators. It is part of ACS +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.- @@ -990,13 +990,13 @@GzipExecutableDirectory +- GzipExecutableDirectory This directory points to where thegunzip program can be found for uncompressinggzip archives. This is needed for the installation of.apm files which are simplygzip ed @@ -979,7 +979,7 @@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 ACS 3.3, and as of version 4.0 offers a -stable set of features. One major feature planned is integration with the ACS + 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 ACS systems. +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 @@ -1042,10 +1042,10 @@ -
- Document Revision # - Action Taken, Notes - When? + By Whom? + Document Revision # + Action Taken, Notes + When? By Whom? Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml 24 Dec 2001 19:31:43 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,5 +1,5 @@ -
- ACS 4 Package Manager Requirements ++ OpenACS 4 Package Manager Requirements by Bryan Quinn andTodd Nightingale @@ -9,7 +9,7 @@Introduction -The following is a requirements document for the ACS Package Manager + 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: @@ -29,7 +29,7 @@To differentiate these new requirements from the requirements of version 3.3, all requirements new in v4 are prefaced with the number - +4 .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 @@ -49,16 +49,16 @@ system, content management system, etc. For such applications and subsystem components, modularity - or the degree to which a component can be encapsulated and decoupled from the rest of the system - is of great value. -Thus the ACS Package Manager (APM) was created to allow website components, +Thus the OpenACS Package Manager (APM) was created to allow website components, or packages, to be added, removed, and upgraded easily, with minimum 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 ACS components in a standardized manner to other -ACS sites. +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 -well-defined purpose. The ACS Package Manager (APM) provides a mechanism for -packaging, installing, and configuring ACS software in a consistent, +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. @@ -67,14 +67,14 @@System Overview -The ACS Package Manager (APM) consists of: +The OpenACS Package Manager (APM) consists of: - + A standard format for APM packages including:- A standard format for APM packages including:- - Version numbering, independent of any other package and the ACS as a + Version numbering, independent of any other package and the OpenACS as a whole @@ -87,7 +87,7 @@ Specification of the package interface + Web-based tools for package management: - Web-based tools for package management: @@ -101,7 +101,7 @@ Obtaining packages from a remote distribution point - Configuring packages (obsoleting the monolithic ACS configuration + Configuring packages (obsoleting the monolithic OpenACS configuration file) @@ -112,13 +112,13 @@ Upgrading packages, without clobbering local modifications A registry of installed packages , database-backed and +- A registry of installed packages , database-backed and integrated with file system-based version control+ Web-based tools for package development: Web-based tools for package development: @@ -128,13 +128,13 @@ Creating new packages locally Uploading packages to a global package repository on the web +should never break an OpenACS installation Use of these tools should be safe, i.e. installing or removing a package -should never break an ACS installation + Web-based tools for package configuration: Web-based tools for package configuration: The ability to change package parameter values on-line through a simple @@ -159,43 +159,43 @@ overlap: - -Developers (referred to as 'the developer') use +- 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.Site-wide administrators (referred to as 'the -administrator') use the APM to install packages for their ACS instance, +- 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.Sub-site administrators (referred to as 'the +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 - Initial Package Development - David Developer writes a piece of software used to do -knowledge management (km) for the ACS. He distributes his data model, ++available for download at the OpenACS package repository. 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 withPatricia -Programmer 's Super Widget toolkit, he specifies that as a +UI. Noting that his software was built withPatricia +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 ArsDigita package repository.+ Initial Package Installation - Initial Package Installation Annie Admin learns of David's KM system by browsing -the ArsDigita package repository. Annie Admin uses the APM administrator UI +- 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 dependency checker notices that Patricia's Super Widget toolkit is required, so it warns Annie of this. Annie selects an option to find a -package that satisfies the dependency at the ArsDigita APM repository. The +package that satisfies the dependency at the OpenACS APM repository. The APM informs Annie that it can download and install Jim's Super Widget toolkit. Annie confirms this option. After successfully installing Jim's toolkit, Annie proceeds to install David's KM system. The data model is @@ -207,13 +207,13 @@ 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 Initial Subsite Use of Package Annie Admin decides to make the KM module available only to a particular -sub-site type on her ACS system, and not others. She specifies this option +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 +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. @@ -222,7 +222,7 @@ the package, Sally decides to change some parameters using the SubAdmin UI. These changes take effect immediately, without any server restarts.+ Upgrade Process 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 @@ -239,9 +239,9 @@ Once Annie upgrades the package, the new version starts working immediately in Sally's sub-site. -+ Procedural API - Procedural API Danielle Developer wants her software to perform +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 @@ -268,30 +268,30 @@- 4.500.0 Package Identification +- - 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 ACS site must be maintained by the APM. For +- 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 +- 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 +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://software.arsdigita.com/packages/apm.apm." +example, "http://openacs.org/software."4.505.0 Version Identification +@@ -311,14 +311,14 @@ - 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 +- 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.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.- + 4.400.0 Packages Status Predicates - - 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 ACS +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.410.0 Sub-site Procedures - - 4.410.0 Sub-site Procedures 4.410.1 After a package has been installed at the +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.0 Parameter Values (replaces ad_parameter) 4.415.1 The system API shall allow subsite parameters for +- 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 +4.415.5 Parameters for a given subsite and package can be returned by the system API.
