apm-requirements.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="apm-requirements" xreflabel="Package Manager Requirements">
<title>Package Manager Requirements</title>
<authorblurb>
<para>By Bryan Quinn and Todd Nightingale</para>
</authorblurb>
<sect2 id="apm-requirements-intro">
<title>Introduction</title>
<para>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:</para>
<itemizedlist>
<listitem><para>A public procedural API. (v 3.3 only has web-based UI)</para></listitem>
<listitem><para>Support for dependency checking.</para></listitem>
<listitem><para>Support for compound packages (to support installation chaining).</para></listitem>
<listitem><para>Support for on-line parameter setting.</para></listitem>
<listitem><para>Support for sub-site level configuration (requires revised parameter
and /admin pages at sub-site level; deprecation of site-wide parameter
file).</para></listitem>
</itemizedlist>
<para>To differentiate these new requirements from the requirements of version
3.3, all requirements new in v4 are prefaced with the number
<emphasis role="strong">4</emphasis>.</para>
<para>We gratefully acknowledge the authors of APM 3 for their original design
documentation which suggested these features, as well as the influence of the
design and open-source implementation of the Red Hat Package manager, the
Debian packaging system, and PERL's CPAN in the development of the ideas
behind this document.</para>
</sect2>
<sect2 id="apm-requirements-vision">
<title>Vision Statement</title>
<para>A typical website will tend to offer its users a number of web-based
services or applications, e.g. a bulletin board, calendaring, classified ads,
etc. A website may also have underlying subsystems, such as a permissions
system, content management system, etc. For such applications and subsystem
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 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 OpenACS components in a standardized manner to other
OpenACS sites.</para>
<para>In general, a package is a unit of software that serves a single
well-defined purpose. The OpenACS Package Manager (APM) provides a mechanism for
packaging, installing, and configuring OpenACS software in a consistent,
user-friendly, and subsite-aware manner.</para>
</sect2>
<sect2 id="apm-requirements-system-overview">
<title>System Overview</title>
<para>
The OpenACS Package Manager (APM) consists of:
</para>
<itemizedlist>
<listitem><para><emphasis role="strong">A standard format for APM packages</emphasis> including: </para>
<itemizedlist>
<listitem><para>Version numbering, independent of any other package and the OpenACS as a
whole</para></listitem>
<listitem><para>Specification of the package interface</para></listitem>
<listitem><para>Specification of dependencies on other packages (if any)</para></listitem>
<listitem><para>Attribution (who wrote it) and ownership (who maintains it)</para></listitem>
</itemizedlist>
</listitem>
<listitem><para><emphasis role="strong">Web-based tools for package management:</emphasis> </para>
<itemizedlist>
<listitem><para>Obtaining packages from a remote distribution point</para></listitem>
<listitem><para>Installing packages, if and only if: </para>
<orderedlist>
<listitem><para>All prerequisite packages are installed</para></listitem>
<listitem><para>No conflicts will be created by the installation</para></listitem>
</orderedlist>
</listitem>
<listitem><para>Configuring packages (obsoleting the monolithic OpenACS configuration
file)</para></listitem>
<listitem><para>Upgrading packages, without clobbering local modifications</para></listitem>
<listitem><para>Uninstalling unwanted packages</para></listitem>
</itemizedlist>
</listitem>
<listitem><para><emphasis role="strong">A registry of installed packages</emphasis>, database-backed and
integrated with filesystem-based version control
</para></listitem>
<listitem><para><emphasis role="strong">Web-based tools for package development:</emphasis> </para>
<itemizedlist>
<listitem><para>Creating new packages locally</para></listitem>
<listitem><para>Releasing new versions of locally-created packages</para></listitem>
<listitem><para>Uploading packages to a global package repository on the web</para></listitem>
<listitem><para>Use of these tools should be safe, i.e. installing or removing a package
should never break an OpenACS installation</para></listitem>
</itemizedlist>
</listitem>
<listitem><para><emphasis role="strong">Web-based tools for package configuration:</emphasis> </para>
<itemizedlist>
<listitem><para>The ability to change package parameter values on-line through a simple
web interface.</para></listitem>
<listitem><para>A new ad_parameter which does not require a monolithic site-wide
parameter's file or server restarts for changes to take effect.</para></listitem>
<listitem><para>The ability to manage multiple package instances at the sub-site
level.</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="apm-requirements-use-cases">
<title>Use-cases and User-scenarios</title>
<para>
The APM is intended for the following classes of users, which may or may not
overlap: </para>
<orderedlist>
<listitem><para><emphasis role="strong">Developers</emphasis> (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.</para></listitem>
<listitem><para><emphasis role="strong">Site-wide administrators</emphasis> (referred to as 'the
administrator') use the APM to install packages for their OpenACS instance,
and optionally make them available to sub-sites.</para></listitem>
<listitem><para><emphasis role="strong">Sub-site administrators</emphasis> (referred to as 'the
sub-admin') use an administration interface to configure and enable
packages for their sub-site.</para></listitem>
</orderedlist>
<para><emphasis role="strong">Initial Package Development</emphasis></para>
<para><emphasis role="strong">David Developer</emphasis> writes a piece of software used to do
knowledge management (km) for the OpenACS. He distributes his data model,
procedure code, UI pages, and his documentation according to the APM
specification. He splits the documentation and the code into sub-packages,
and creates a KM installation-chain to install both with the APM developer
UI. Noting that his software was built with <emphasis role="strong">Patricia
Programmer</emphasis>'s Super Widget toolkit, he specifies that as a
dependency. Moreover, since this package is capable of being used at the
sub-site level, David configures this option in the package. When the package
development is complete, David uses the APM developer UI to construct a
distribution file. He assigns it a version number, 1.0, and makes the package
available for download at the OpenACS package repository.</para>
<para><emphasis role="strong">Initial Package Installation</emphasis></para>
<para><emphasis role="strong">Annie Admin</emphasis> 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 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
loaded and all of the files necessary for the software are installed. Because
installation was successful, the package is available for use.</para>
<para>Since the package is available for use, its initialization routines are
set to run automatically on server startup. Annie is warned that since there
are initialization routines, she must restart the server for the package to
be ready for use. Annie restarts the server.</para>
<para><emphasis role="strong">Initial Subsite Use of Package</emphasis></para>
<para>Annie Admin decides to make the KM module available only to a particular
sub-site type on her OpenACS system, and not others. She specifies this option
using the Sub-site type UI (not part of APM).</para>
<para>Annie Admin notifies <emphasis role="strong">Sally SubAdmin</emphasis> by e-mail that a new
package is now available for use. Sally goes to her sub-site /admin page and
sees that a new entry, KM, is available. Sally clicks on it and finds links
to the installed KM documentation and to the web based configuration utility.
Then, Sally configures the package using an automatically generated web
interface and enables KM for use on her sub-site. After some initial use of
the package, Sally decides to change some parameters using the SubAdmin UI.
These changes take effect immediately, without any server restarts.</para>
<para><emphasis role="strong">Upgrade Process</emphasis></para>
<para>Sally SubAdmin finds a bug in the KM system and sends a report to David
Developer. David reads the bug report and verifies that the bugs are present
in the current version. Because the bugs are present in the shared procedure
file, David assigns a watch to the file. David makes the necessary
modifications to the source code and saves the file. Because a watch was
assigned to the file, the APM automatically reloads the updated code. David
tests the program and confirms that the bug is fixed. He increments the minor
version number and makes km v 1.1 available for download at the
repository.</para>
<para>Sally SubAdmin asks Annie Administrator to upgrade the package using the
APM UI. This upgrade supersedes the old version of KM at the site-wide level.
Once Annie upgrades the package, the new version starts working immediately
in Sally's sub-site.</para>
<para><emphasis role="strong">Procedural API</emphasis></para>
<para><emphasis role="strong">Danielle Developer</emphasis> wants her software to perform
different actions depending on what version of another package is installed.
She uses the APM procedural API to check if KM version 1.0 is installed or
version 1.1. Based on the results of this procedural call, the software
exhibits different behavior.</para>
</sect2>
<sect2 id="apm-requirements-links">
<title>Related Links</title>
<itemizedlist>
<listitem><para><ulink url="apm-design">APM 3.3 Design document</ulink></para></listitem>
<listitem><para><ulink url="packages">Five minute guide to packaging a module</ulink></para></listitem>
<listitem><para><ulink url="subsites-requirements">Sub-sites</ulink></para></listitem>
</itemizedlist>
</sect2>
<sect2 id="apm-requirements-data-model">
<title>Requirements: Data Model</title>
<itemizedlist>
<listitem><para><emphasis role="strong">4.500.0 Package Identification</emphasis>
(All of these items are entered by the developer using the developer UI.) </para>
<para><emphasis role="strong">4.500.1</emphasis> 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."</para>
<para><emphasis role="strong">4.500.5</emphasis> A package id (primary key) that is guaranteed to
be unique to the local site must be maintained by the APM. For example,
"25."</para>
<para><emphasis role="strong">4.500.10</emphasis> A package URL that is guaranteed to be unique
across all sites must be maintained by the APM. The package URL should point
to a server that allows download of the latest version of the package. For
example, "http://openacs.org/software."
</para></listitem>
<listitem><para><emphasis role="strong">4.505.0 Version Identification</emphasis>
(All of these items are entered by the developer using the developer UI.) </para>
<para><emphasis role="strong">4.505.1</emphasis> A version id (primary key) that is guaranteed to
be unique to the local site must be maintained by the APM.</para>
<para><emphasis role="strong">4.505.5</emphasis> 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.
</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="apm-requirements-api">
<title>Requirements: API</title>
<para>The API for APM v3 is explicitly a private API. However, it would be
useful to obtain information from the APM through a procedural API.
Implementing the API specified below is quite easy given that there are pages
that already do all of the below in raw SQL.</para>
<itemizedlist>
<listitem><para><emphasis role="strong">4.400.0 Packages Status Predicates</emphasis> </para>
<para><emphasis role="strong">4.400.1</emphasis> Given defining information such as a package URL,
the APM API can return the status of the package on the local OpenACS
instance.</para>
<!--
<para><emphasis role="strong">4.400.1</emphasis> Given a package's URL, the system API can be
queried for the existence of that installed package locally.
<computeroutput>apm_package_installed_p
{package_url}</computeroutput>
Returns 1 if the specified package is installed, 0 otherwise.
<emphasis role="strong">4.400.5</emphasis> Given a specific version URL of a package, the
system API can be queried for the existence of that specific
version locally: whether it is installed or not, for instance.
<computeroutput>apm_version_installed_p {version_url}</computeroutput>
Returns 1 if the specified version is installed, 0 otherwise.
<emphasis role="strong">4.400.10</emphasis> The system API can be queried for whether or
not a package (that has already been installed locally) has been
loaded and initialized. </para>
<computeroutput>apm_version_loaded_p {version_id}</computeroutput><para>
Returns 1 if a version of a package has been loaded and initialized, or 0 otherwise.
-->
</listitem>
<listitem><para><emphasis role="strong">4.405.0 Package Information Procedures</emphasis> </para>
<para><emphasis role="strong">4.405.1</emphasis> The APM API can return information for any
locally installed packages, including the version number, paths and files,
and package key.</para>
<!--
<para><emphasis role="strong">4.405.1</emphasis> Given a package_url, the system API can
determine and return the locally installed version number, if
any.
<computeroutput>apm_package_version_installed {package_url}</computeroutput>
Returns the installed version number of the specified
package_url. If the package is not installed, returns 0.
<emphasis role="strong">4.405.5</emphasis> Given a version number (presumably of an
already installed package), the system can return the associated
list of paths and files (within a given type also, is specified).
<computeroutput>apm_version_file_list { { -type "" } version_id }</computeroutput>
Returns a list of paths to files of a given type (or all files, if
$type is not specified) in a version.
<emphasis role="strong">4.405.10</emphasis> <computeroutput>apm_version_id_from_url { version_url }</computeroutput>
If a package version with the specified version_url is
installed, this procedure returns its version_id. Else, it
returns 0.
<emphasis role="strong">4.405.15</emphasis> <computeroutput>apm_package_id_from_version_id { version_id }</computeroutput>
Given a valid version id, returns the associated package id.
Otherwise returns 0.
<emphasis role="strong">4.405.20</emphasis> <computeroutput>apm_package_key_from_package_id { package_id }</computeroutput>
Given a valid package id, returns the associated package key.
Otherwise returns 0.
<emphasis role="strong">4.405.25</emphasis> <computeroutput>apm_package_id_from_package_key { package_key }</computeroutput>
Given a valid package key, returns the associated package id.
Otherwise returns 0.
-->
</listitem>
<listitem><para><emphasis role="strong">4.410.0 Sub-site Procedures</emphasis> </para>
<para><emphasis role="strong">4.410.1</emphasis> 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.</para>
<!--
<para><emphasis role="strong">4.410.1</emphasis> <computeroutput>apm_package_available_subsite_spec_p { package_id
subsite_spec_id }</computeroutput> Returns 1 if the indicated package
is contained in the indicated sub-site_spec. Returns 0 otherwise.
<emphasis role="strong">4.410.5</emphasis> <computeroutput>apm_package_available_subsite_p { package_id
subsite_id }</computeroutput> Returns 1 if the indicated package is
can be created as an instance for the indicated sub-site.
Returns 0 otherwise.
<emphasis role="strong">4.410.10</emphasis> <computeroutput>apm_package_instance_subsite_p { package_id
subsite_id }</computeroutput> Returns 1 if the indicated package is
available as an instance in the indicated sub-site. Returns 0
otherwise.
<emphasis role="strong">4.410.15</emphasis> <computeroutput>apm_package_enabled_subsite_p { package_id
subsite_id }</computeroutput> Returns 1 if the indicated package is
enabled in the indicated sub-site. Returns 0 otherwise.
<emphasis role="strong">4.410.20</emphasis> <computeroutput>apm_package_add_to_subsite_spec
{package_id subsite_spec_id} </computeroutput> If package_id corresponds
to an installed package and sub-site_spec_id specifies a valid
sub-site, adds that package to the sub-site spec. Throws an error
otherwise.
<emphasis role="strong">4.410.25</emphasis> <computeroutput>apm_package_remove_from_subsite_spec
{package_id subsite_spec_id} </computeroutput> If package_id corresponds
to an installed package and sub-site_spec_id specifies a valid
sub-site, removes that package from the sub-site spec. Throws
an error otherwise.
<emphasis role="strong">4.410.30</emphasis> <computeroutput>apm_package_instance_new { package_id
subsite_id }</computeroutput> If package_id corresponds to a package
that can be created for the indicated sub-site, create the new
instance. Throws an error otherwise.
<emphasis role="strong">4.410.35</emphasis> <computeroutput>apm_package_instance_nuke { package_id
subsite_id }</computeroutput> If package_id is a package_instance for
the indicated sub-site, delete the instance and all associated
content. Throws an error otherwise.
<emphasis role="strong">4.410.40</emphasis> <computeroutput>apm_enable_package_for_subsite { package_id
subsite_id }</computeroutput> If package_id is available as an instance
for the indicated sub-site, enables it. Throws an error
otherwise.
<emphasis role="strong">4.410.45</emphasis> <computeroutput>apm_disable_package_for_subsite { package_id
subsite_id }</computeroutput> If package_id is available as an instance
for the indicated sub-site, disables it. Throws an error otherwise.
-->
</listitem>
<listitem><para><emphasis role="strong">4.415.0 Parameter Values (replaces ad_parameter)</emphasis> </para>
<para><emphasis role="strong">4.415.1</emphasis> 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).</para>
<para><emphasis role="strong">4.415.5</emphasis> Parameters for a given subsite and package can be
returned by the system API.</para>
<!--
<para><emphasis role="strong">4.415.1</emphasis> <computeroutput>apm_set_parameter {{-persistent t}
{-on_restart f} {-subsite_id "OBTAIN AUTOMATICALLY" {parameter value
package_key}</computeroutput> Sets the
indicated parameter for the indicated package in the indicated
sub-site to the given value. User must be an administrator of
the sub-site_id to be able to do this. If persistent is true,
the value is preserved across server restarts. If on_restart is
true, the new value will take effect on server restart.
<emphasis role="strong">4.415.5</emphasis> <computeroutput>apm_get_parameter {{-default ""}
{-subsite_id "OBTAIN AUTOMATICALLY" }parameter
package_key }</computeroutput> Returns the value of the parameter for
the indicated package and sub-site. If no value is found,
returns the given default, else empty string.
-->
</listitem>
</itemizedlist>
</sect2>
<sect2 id="apm-requirements-security">
<title>Requirements: Security</title>
<para>
Provisions will be made to assure that packages are securely
identified.</para>
<itemizedlist>
<listitem><para><emphasis role="strong">4.600.1</emphasis> Each package will have a PGP signature and there
will be MD5 timestamps for each file within the package.
</para></listitem>
<listitem><para><emphasis role="strong">4.600.5</emphasis> The APM will provide a facility to validate both
the PGP signature and MD5 stamps information before a package install.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="apm-requirements-ui">
<title>Requirements: The User Interface</title>
<para>The user interface is a set of HTML pages that are used to drive the
underlying API. It is restricted to site-wide administrators because the
actions taken here can dramatically affect the state of the running OpenACS.</para>
</sect2>
<sect2 id="apm-requirements-dev-interface">
<title>Requirements: The Developer's Interface</title>
<para>The intent of the developer's interface is to enable the developer to
construct and maintain APM packages. It will be possible to disable the
developer's interface for production sites to help reduce the chance of
site failure; much of the functionality here can have cascading effects
throughout the OpenACS and should not be used on a production site.</para>
<itemizedlist>
<listitem><para><emphasis role="strong">10.0 Define a package.</emphasis></para>
<para>The developer must be able to create a new package by specifying some
identifying information for the package. This includes a package name, a
package key, version information, owner information, and a canonical URL.</para>
<para><emphasis role="strong">10.1</emphasis> The APM must maintain the state of all locally
generated packages.</para>
<para><emphasis role="strong">10.50</emphasis> If the developer fails to provide the required
information, the package cannot be created.</para>
<para><emphasis role="strong">10.55</emphasis> All of the package information should be editable
after creation, except for the package key.</para>
<para><emphasis role="strong">4.10.60</emphasis> The package creator must specify whether the
package is capable of being used in sub-sites, or if only a single, global
instance of the package is permitted.</para>
<para><emphasis role="strong">4.10.65</emphasis> If the developer fails to provide unique
information for unique fields specified in the data model requirements, the
package cannot be created.</para>
</listitem>
<listitem><para><emphasis role="strong">20.0 Add files to a package</emphasis> </para>
<para><emphasis role="strong">20.1</emphasis> The developer must be able to add files to the
package. This is done by copying the files into the package directory in the
host OS's filesystem. Files can be added at any point after package
creation.</para>
<para><emphasis role="strong">20.3</emphasis> Once a package has been versioned and distributed,
no new files should be added to the package without incrementing the version
number.</para>
<para><emphasis role="strong">20.5</emphasis> The APM's UI should facilitate the process of
adding new files, by scanning the filesystem for new files automatically,
and allowing the developer to confirm adding them.</para>
<para><emphasis role="strong">20.10</emphasis> The developer cannot add files to a given package
via the UI that do not exist in the filesystem already.</para>
<para><emphasis role="strong">20.15</emphasis> Package file structure must follow a specified
convention. Please see the <link linkend="apm-design">design
document</link> for what we do currently.</para>
</listitem>
<listitem><para><emphasis role="strong">30.0 Remove files from a package</emphasis></para>
<para>The developer must be able to remove files from a package. This can be
done in two ways.</para>
<itemizedlist>
<listitem><para><emphasis role="strong">30.1</emphasis> Access the APM UI, browse the file list, and remove
files.</para>
<para><emphasis role="strong">30.1.1</emphasis>If a file is removed from the package list, but not
from the filesystem, an error should be generated at package load time.</para>
</listitem>
<listitem><para><emphasis role="strong">30.5</emphasis> Remove the file from filesystem. </para>
<para><emphasis role="strong">30.5.1</emphasis> The APM UI should take note of the fact that the
file is gone and offer the developer an option to confirm the file's
deletion.
</para></listitem>
</itemizedlist>
</listitem>
<listitem><para><emphasis role="strong">40.0 Modify files in a package</emphasis>. </para>
<para><emphasis role="strong">40.1</emphasis> The developer should be able to modify files in the
filesystem. The APM UI should not interfere with this.</para>
<para><emphasis role="strong">40.5</emphasis> However, if the developer modifies files containing
procedural definitions, APM UI should allow a means to <emphasis role="strong">watch</emphasis>
those files and automatically reload them if changed. See requirement 50.0
for more detail.</para>
<para><emphasis role="strong">40.10</emphasis> Also, although a change in files implies that the
package distribution file is out of date, it is the developer's
responsibility to update it.</para>
</listitem>
<listitem><para><emphasis role="strong">4.45.0 Manage Package Dependency Information</emphasis>. </para>
<para><emphasis role="strong">4.45.1</emphasis> The developer should be able to specify which
interfaces the package requires.</para>
<para><emphasis role="strong">4.45.5</emphasis> The developer should be able to specify which
interfaces the package provides.</para>
<para><emphasis role="strong">4.45.10</emphasis> Circular dependencies are not allowed.</para>
</listitem>
<listitem><para><emphasis role="strong">50.0 Watch a file</emphasis> </para>
<para><emphasis role="strong">4.50.1</emphasis> The developer should be able to assign a watch to
any Tcl procedure file, whether in /packages or /tcl.</para>
<para><emphasis role="strong">50.5</emphasis> If a watched file is locally modified, then it will
be automatically reloaded, thus allowing for any changes made to take affect
immediately.</para>
<para><emphasis role="strong">4.50.10</emphasis> The setting of a watch should be persistent
across server restarts.
</para></listitem>
<listitem><para><emphasis role="strong">60.0 Display an XML package specification</emphasis> </para>
<para><emphasis role="strong">60.1</emphasis> The developer should be able to view the XML package
specification that encodes all package information.
</para></listitem>
<listitem><para><emphasis role="strong">70.0 Write an XML package specification to the filesystem</emphasis> </para>
<para><emphasis role="strong">70.1</emphasis> The developer should be able to write an up-to-date
XML specification to disk.</para>
<para><emphasis role="strong">70.5</emphasis> The developer should be able to request the current
XML specification for all installed, locally generated packages.</para>
</listitem>
<listitem><para><emphasis role="strong">130.0 Distribution file generation</emphasis> </para>
<para><emphasis role="strong">130.1</emphasis> The developer should be able to generate a .APM
distribution file for the package with just one click.</para>
<para><emphasis role="strong">130.5</emphasis> Generating a distribution file implies doing an
"up-to-date" check on all of the files. If any of the files have
changed since package installation, then a new version of the package is
created.
</para></listitem>
<listitem><para><emphasis role="strong">140.0 Access CVS information</emphasis> </para>
<para><emphasis role="strong">140.1</emphasis> The developer should be able to determine the CVS
status of a package, or all packages, with a single click.
</para></listitem>
<listitem><para><emphasis role="strong">4.400.0 Compound Package Construction</emphasis> </para>
<para><emphasis role="strong">4.400.1</emphasis> The developer can include .APM packages
(sub-packages) within a package (the compound package) like any other
file.</para>
<para><emphasis role="strong">4.400.5</emphasis> The recommended usage for this feature is to
allow for separation of optional and required components from the
installation as well as better organization of files once installed. For
example, all documentation for the community-core can be packages as
<computeroutput>community-core-doc.apm</computeroutput>. It is legal to include sub-packages with
dependencies that are not satisfied by the packages in the compound package,
but this is discouraged. In such a case, the sub-package should really be a
separate package that is required by the compound package.</para>
<para><emphasis role="strong">4.400.10</emphasis> If a sub-package is required for the
installation of the compound package, the compound package should have a
registered dependency on the sub-package.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="apm-requirements-admin-interface">
<title>Requirements: The Site-Wide Administrator's Interface</title>
<para>The requirement of the administrator's interface is to enable the
administrator to install, enable, upgrade, disable, deinstall, and delete
packages.</para>
<itemizedlist>
<listitem><para><emphasis role="strong">80.0 Package Enable/Disable</emphasis> </para>
<para><emphasis role="strong">4.80.1</emphasis> The administrator should be able mark an installed
package as enabled. This means that the package is activated and its
functionality is delivered through the Request Processor. As of OpenACS 4, this
is done through the sub-site system.</para>
<para><emphasis role="strong">4.80.5</emphasis> Moreover, the administrator must be able to
disable a package, thereby removing the functionality provided to a sub-site.
As of OpenACS 4, this is done through the sub-site system.
</para></listitem>
<listitem><para><emphasis role="strong">90.0 Package Install</emphasis> </para>
<para><emphasis role="strong">90.1</emphasis> The administrator must be able to install new
packages either from locally maintained .APM files or from URLs.</para>
<para><emphasis role="strong">90.5</emphasis> In the case of a URL, the APM transparently
downloads the APM file off the web, proceeds with a file based installation,
and then optionally removes the .APM file just downloaded.</para>
<para><emphasis role="strong">90.10.1</emphasis> If .APM files are present in a package, then it
is considered a compound package (use 4.410.0).</para>
<para><emphasis role="strong">90.15.0</emphasis> Installation requires these steps:</para>
<orderedlist>
<listitem><para><emphasis role="strong">90.15.1</emphasis>The package dependencies are scanned. If some
dependencies are not present, the system warns the administrator that
installation cannot proceed until those packages are installed.</para></listitem>
<listitem><para><emphasis role="strong">90.15.2</emphasis> Assuming all dependencies are present, APM
extracts the contents of the APM file into the /packages directory.</para></listitem>
<listitem><para><emphasis role="strong">90.15.3</emphasis> The administrator is offered the option of
importing directly into CVS.</para></listitem>
<listitem><para><emphasis role="strong">90.15.4</emphasis> The administrator is given a list of data model
scripts found in the package and can select which ones to be executed.</para></listitem>
<listitem><para><emphasis role="strong">90.15.5</emphasis> If no errors are recorded during this process,
the package is enabled.</para></listitem>
</orderedlist>
</listitem>
<listitem><para><emphasis role="strong">4.410.0 Compound package Install</emphasis> </para>
<para><emphasis role="strong">4.410.1</emphasis> If .APM files are present in a package, then it
is considered a compound package.</para>
<para><emphasis role="strong">4.410.5.0</emphasis> Installation of a compound package proceeds
according to the following sequence:</para>
<orderedlist>
<listitem><para><emphasis role="strong">4.410.5.1</emphasis> Identify the set of all sub-packages within
the compound package by scanning for all files with .APM.</para></listitem>
<listitem><para><emphasis role="strong">4.410.5.2</emphasis> Identify which sub-packages are required by
checking the dependencies of the compound package. If there dependencies not
satisfied by the current system or the packages included with the compound
package, halt installation and inform user to install these packages
first.</para></listitem>
<listitem><para><emphasis role="strong">4.410.5.3</emphasis> Present Administrator with the ability to
choose which sub-packages to install. Required sub-packages must be
installed.</para></listitem>
<listitem><para><emphasis role="strong">4.410.5.4</emphasis> Proceed with the installation of each
sub-package, starting with required packages. If the sub-package is already
installed, then do nothing. Else, If the sub-package is a normal package,
proceed according to <emphasis role="strong">90.15.0</emphasis>, otherwise if it is a compound
package, proceed according to <emphasis role="strong">4.410.5.0</emphasis>.</para></listitem>
<listitem><para><emphasis role="strong">4.410.5.5</emphasis> If all required sub-packages are installed,
proceed to install non-required sub-packages. If there was a failure during
the installation of a required sub-package, then the installation of the
compound package is also a failure.</para></listitem>
<listitem><para><emphasis role="strong">4.410.5.6</emphasis> Any attempt to install a compound package in
the future involves a choice presented to the admin of installing any
uninstalled sub-packages.</para></listitem>
</orderedlist>
</listitem>
<listitem><para><emphasis role="strong">4.420.0 Recovering from failed package installation</emphasis></para>
<para><emphasis role="strong">4.420.1</emphasis> If any error is generated during package
installation, the package is not considered installed. To recover from this
failure, the package should be selected for installation again.</para>
</listitem>
<listitem><para><emphasis role="strong">100.0 Version Upgrade</emphasis> </para>
<para><emphasis role="strong">100.1</emphasis> The administrator can upgrade to a new version of a
package. This entails</para>
<orderedlist>
<listitem><para><emphasis role="strong">100.1.1</emphasis> Running any necessary and included upgrade
scripts.</para></listitem>
<listitem><para><emphasis role="strong">100.1.5</emphasis> Replacing any old files with new versions.</para></listitem>
<listitem><para><emphasis role="strong">100.1.10</emphasis> Marking the old version of the package as
'superseded' and disabling it.</para></listitem>
<listitem><para><emphasis role="strong">100.1.15</emphasis> Assuming no errors from above, the new package
is enabled.</para></listitem>
</orderedlist>
</listitem>
<listitem><para><emphasis role="strong">110.0 Package Deinstall</emphasis> </para>
<para><emphasis role="strong">110.1</emphasis> The administrator must be able to deinstall a
package that has already been installed. Deinstallation entails:</para>
<orderedlist>
<listitem><para><emphasis role="strong">110.1.1</emphasis> Running any data model scripts necessary to drop
the package.</para></listitem>
<listitem><para><emphasis role="strong">110.1.5</emphasis> Moving all of the files into a separate location
in the filesystem from the installed packages.</para></listitem>
<listitem><para><emphasis role="strong">4.110.1.10</emphasis> If the package is a compound package, then
the administrator must confirm removing all sub-packages. Optionally, some
sub-packages can be kept.</para></listitem>
</orderedlist>
<para><emphasis role="strong">110.5</emphasis> Deinstalled packages can be re-installed at a later
date.</para>
<para><emphasis role="strong">4.110.10</emphasis> If deinstalling a package or any of its
sub-packages breaks a dependency, then deinstallation cannot proceed until
the package registering the dependency is removed.</para>
</listitem>
<listitem><para><emphasis role="strong">120.0 Package Deletion</emphasis> </para>
<para><emphasis role="strong">120.1</emphasis> The administrator should be able to completely
erase all records of the package. This involves removing all instances of the
package, all related database tables and content.</para>
<para><emphasis role="strong">120.5</emphasis> This option can only be used if all package
instances are deleted or marked as disabled. This is purposefully cumbersome
because deleting all instances of a package can have far-sweeping
consequences throughout a site and should almost never be done.</para>
</listitem>
<listitem><para><emphasis role="strong">150.0 Scan for new or modified packages</emphasis> </para>
<para><emphasis role="strong">150.1</emphasis> The administrator should be able to scan the filesystem for any changes made in any of the installed package files.</para>
<para><emphasis role="strong">150.5</emphasis> The administrator should be able to scan the filesystem for any newly installed packages.
</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="apm-requirements-sub-admin-intf">
<title>Requirements: The Sub-Site Administrator's Interface</title>
<para>
If the developer is in charge of creating packages and the administrator for
installing them, then the sub-site administrator is responsible for
configuring and enabling packages. In order for a package to be available for
a sub-site it must be associated with the sub-site's type specification.
This interface is part of the sub-site /admin interface.
</para>
<itemizedlist>
<listitem><para><emphasis role="strong">4.300</emphasis> Creating a package instance. </para>
<para><emphasis role="strong">4.300.1</emphasis> From the sub-site /admin interface, there should
be an option to view all packages available in the system as well as an
option to add a package to the subsite.</para>
<para><emphasis role="strong">4.300.5</emphasis> From the "add" option, the sub-admin
can select from a list of packages registered as available in the sub-site
type to which the sub-site belongs.</para>
<para><emphasis role="strong">4.300.19</emphasis> Once a package instance is added, it is
available on the list of the subsite's available packages.</para>
</listitem>
<listitem><para><emphasis role="strong">4.305</emphasis> Configuring a package instance. </para>
<para><emphasis role="strong">4.305.1</emphasis> An automatic web interface that lists all
parameters with current values must be available.</para>
<para><emphasis role="strong">4.305.5</emphasis> Changing the values for the parameters is
accomplished simply by submitting an HTML form.</para>
</listitem>
<listitem><para><emphasis role="strong">4.310</emphasis> Enabling a package instance. </para>
<para><emphasis role="strong">4.310.1</emphasis> The sub-admin should be able to enable a package
with a single click. Enabling a package means that the OpenACS will serve its
URLs properly.
</para></listitem>
<listitem><para><emphasis role="strong">4.315</emphasis> Disabling a package instance. </para>
<para><emphasis role="strong">4.315.1</emphasis> The sub-admin should be able to disable a package
with a single click. Disabling a package means that the OpenACS will no longer
serve those URLs.</para>
</listitem>
<listitem><para><emphasis role="strong">4.320</emphasis> Deleting a package instance. </para>
<para><emphasis role="strong">4.320.1</emphasis> Deleting a package instance involves deleting not
only the package instance, but any and all content associated with it. It is
questionable whether this option should even be available due to its drastic
consequences. Reviewer comments appreciated.
</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="apm-requirements-implementation">
<title>Implementation notes</title>
<para>Despite the fact that requirements are meant to be design/implementation
neutral, the following thoughts were in our head when specifying these
requirements. You must be familiar with the new object design for this to be
comprehensible.</para>
<para>When a package is installed system-wide, a corresponding acs_object_type
is created for it. All parameters registered for the package are registered
for that acs_object_type.</para>
<para>When a package instance is created, it is an acs_object. Its parameters
are set using the acs_attribute_values table. The automatic web interface for
setting package parameters should be one and the same with the interface for
setting acs object attribute values. Consequently, the implementation of
these features should be quite straightforward.</para>
</sect2>
<sect2 id="apm-requirements-rev-history">
<title>Revision History</title>
<informaltable>
<tgroup cols="4">
<tbody>
<row>
<entry><emphasis role="strong">Document Revision #</emphasis></entry>
<entry><emphasis role="strong">Action Taken, Notes</emphasis></entry>
<entry><emphasis role="strong">When?</emphasis></entry>
<entry><emphasis role="strong">By Whom?</emphasis></entry>
</row>
<row>
<entry>0.1</entry>
<entry>Creation</entry>
<entry>8/10/2000</entry>
<entry>Bryan Quinn, Todd Nightingale</entry>
</row>
<row>
<entry> </entry>
<entry>Reviewed</entry>
<entry>8/11/2000</entry>
<entry>John Prevost, Mark Thomas, and Pete Su</entry>
</row>
<row>
<entry>0.2</entry>
<entry>Revised and updated</entry>
<entry>8/12/2000</entry>
<entry>Bryan Quinn</entry>
</row>
<row>
<entry>0.3</entry>
<entry>Reviewed, revised, and updated - conforms to requirements template.</entry>
<entry>8/18/2000</entry>
<entry>Kai Wu</entry>
</row>
<row>
<entry>0.4</entry>
<entry>Minor edits before ACS 4 Beta.</entry>
<entry>9/30/2000</entry>
<entry>Kai Wu</entry>
</row>
</tbody></tgroup></informaltable>
</sect2>
</sect1>
