Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml,v diff -u -r1.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, 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 @@ -62,22 +62,22 @@ -ACS Applications: a "program or group of programs +OpenACS Applications: a "program or group of programs designed for end users" (the Webopedia definition); also known as modules, for historical reasons. 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 +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 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 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. @@ -203,14 +203,14 @@ - 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 OpenACS Kernel, an OpenACS +service that is the only mandatory component of an OpenACS installation. @@ -220,7 +220,7 @@ 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 has the 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 specification of the package interface @@ -256,7 +256,7 @@ -web-based tools for package management: +web-based tools for package management: obtaining packages from a remote distribution point @@ -270,7 +270,7 @@ -configuring packages (obsoleting the monolithic ACS configuration +configuring packages (obsoleting the monolithic OpenACS configuration file) upgrading packages, without clobbering local modifications @@ -281,13 +281,13 @@ -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: creating new packages locally @@ -310,7 +310,7 @@ 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 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. @@ -343,10 +343,10 @@ on an appropriate URL, and set parameters for that particular instance. -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. @@ -371,9 +371,9 @@ -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 . 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. @@ -398,9 +398,9 @@ -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 cascade_p only if you want to completely remove the -package from the ACS. +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 @@ -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 @@ 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. @@ -585,7 +585,7 @@ Files associated with a version can be added and removed. The path is -relative to the package-root which is +relative to the package-root which is acs-server-root/packages/package-key. @@ -693,7 +693,7 @@ -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 @@ 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: +example, here is how the OpenACS API Documentation service +makes itself available on the OpenACS main site: @@ -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 @@ -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 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. @@ -952,8 +952,8 @@ 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 +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. @@ -970,7 +970,7 @@ need to be tweaked for Windows compatibility. -GzipExecutableDirectory +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 @@ -979,7 +979,7 @@ -InfoFilePermissionsMode +InfoFilePermissionsMode This sets the default UNIX permissions used when creating files using the APM. Default is 775. @@ -990,13 +990,13 @@ 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?