• Publicity: Public Only All

apm-procs.tcl

Routines used by the package manager.

Location:
packages/acs-tcl/tcl/apm-procs.tcl
Created:
13 Apr 2000
Authors:
Bryan Quinn <bquinn@arsdigita.com>
Jon Salz <jsalz@arsdigita.com>
CVS Identification:
$Id: apm-procs.tcl,v 1.118 2024/10/08 14:13:36 antoniop Exp $

Procedures in this file

Detailed information

apm::convert_type (public)

 apm::convert_type -package_id package_id \
    -old_package_key old_package_key -new_package_key new_package_key

Convert a package instance to a new type, doing the proper instantiate and mount callbacks and parameter creation.

Switches:
-package_id (required)
The package instance to convert.
-old_package_key (required)
The package key we're converting from.
-new_package_key (required)
The new subsite type we're converting to.

Testcases:
No testcase defined.

apm::get_package_descendent_options (public)

 apm::get_package_descendent_options package_key

Get a list of pretty name, package key pairs for all packages which are descendents of the given package key.

Parameters:
package_key (required)
The parent package's key.
Returns:
a list of pretty name, package key pairs suitable for use in a template select widget.

Testcases:
No testcase defined.

apm::metrics (public)

 apm::metrics -package_key package_key -file_type file_type \
    [ -array array ]

Return some code metrics about the files in package $package_key. This will return an array or dict containing at least the following items:

  • count - the number of files
  • lines - the number of lines in the files
  • blank_lines - the number of blank lines in the files
  • comment_lines - the number of blank lines in the files
  • procs - the number of procs, if applicable (0 if not applicable)

Valid file_type's:

  • data_model_pg - PG datamodel files
  • data_model_ora - Oracle datamodel files
  • include_page - ADP files in package_key/lib
  • content_page - ADP files in package_key/www
  • tcl_procs - Tcl procs in package_key/tcl
  • test_procs - automated tests in package_key/tcl/test
  • documentation - docs in package_key/www/doc
When the array is provided, it will be used for setting the result. Otherwise a dict with the metrics information is returned. This proc is cached.

Switches:
-package_key (required)
The package_key of interest
-file_type (required)
See options above
-array (optional)
variable to hold the array that will be returned
Author:
Vinod Kurup
Created:
2006-02-09

Testcases:
No testcase defined.

apm_application_new_checkbox (public)

 apm_application_new_checkbox

Return an HTML checkbox of package_key and package names for applications that can be mounted in the site-map. Excludes singletons that are already instantiated.

Author:
Peter Marklund

Testcases:
No testcase defined.

apm_arg_names_for_callback_type (public)

 apm_arg_names_for_callback_type -type type

Return the list of required argument names for the given callback type.

Switches:
-type (required)
Author:
Peter Marklund

Testcases:
acs_admin_require_site_wide

apm_assert_callback_type_supported (public)

 apm_assert_callback_type_supported type

Throw an error if the given callback type is not supported.

Parameters:
type (required)
Author:
Peter Marklund

Testcases:
No testcase defined.

apm_body_callback (public)

 apm_body_callback string

This callback uses the document API to append more text to the stream.

Parameters:
string (required)

Testcases:
No testcase defined.

apm_build_one_package_relationships (public)

 apm_build_one_package_relationships package_key

Builds the nsv dependency structures for a single package.

Parameters:
package_key (required)

Testcases:
No testcase defined.

apm_build_package_relationships (public)

 apm_build_package_relationships

Builds the nsv dependency and ancestor structures.

Testcases:
No testcase defined.

apm_build_subsite_packages_list (public)

 apm_build_subsite_packages_list

Build the nsv_set cache of all packages which claim to implement subsite semantics. The kludge to add acs-subsite if it's not declared with the subsite attribute set true is needed during the upgrade process ...

Testcases:
No testcase defined.

apm_callback_and_log (public)

 apm_callback_and_log [ -severity severity ] callback message

Executes the $callback callback routine with $message as an argument, and calls ns_log with the given $severity.

Switches:
-severity (optional, defaults to "Notice")
Parameters:
callback (required)
message (required)

Testcases:
upgrade

apm_callback_format_args (public)

 apm_callback_format_args [ -version_id version_id ] \
    [ -package_key package_key ] -type type [ -arg_list arg_list ]

Return a string on format -arg_name1 arg_value1 -arg_name2 arg_value2 ... for the callback proc of given type.

Switches:
-version_id (optional)
-package_key (optional)
-type (required)
-arg_list (optional)
Author:
Peter Marklund

Testcases:
apm__test_callback_invoke

apm_callback_has_valid_args (public)

 apm_callback_has_valid_args -type type -proc_name proc_name

Returns 1 if the specified callback proc of a certain type has a valid argument list in its definition and 0 otherwise. Assumes that the callback proc is defined with ad_proc.

Switches:
-type (required)
-proc_name (required)
Author:
Peter Marklund

Testcases:
No testcase defined.

apm_callback_type_supported_p (public)

 apm_callback_type_supported_p type

Return 1 if the given type of callback is supported and 0 otherwise.

Parameters:
type (required)
Author:
Peter Marklund

Testcases:
No testcase defined.

apm_dependency_add (public)

 apm_dependency_add [ -callback callback ] \
    [ -dependency_id dependency_id ] dependency_type version_id \
    dependency_uri dependency_version

Add a dependency to a version.

Switches:
-callback (optional, defaults to "apm_dummy_callback")
-dependency_id (optional)
Parameters:
dependency_type (required)
version_id (required)
dependency_uri (required)
dependency_version (required)
Returns:
The id of the new dependency.

Testcases:
No testcase defined.

apm_dependency_remove (public)

 apm_dependency_remove dependency_id

Removes a dependency from the system.

Parameters:
dependency_id (required)

Testcases:
No testcase defined.

apm_dummy_callback (public)

 apm_dummy_callback string

A dummy callback routine which does nothing.

Parameters:
string (required)

Testcases:
No testcase defined.

apm_enabled_packages (public)

 apm_enabled_packages

Returns a list of package_key's for all enabled packages.

Author:
Peter Marklund

Testcases:
No testcase defined.

apm_flush_package_id_cache (public)

 apm_flush_package_id_cache package_key

Flush the package id cache for this package at least in the current thread. TODO: should be refactored together with the 2level cache (per thread and util_memoize).

Parameters:
package_key (required)

Testcases:
No testcase defined.

apm_get_callback_proc (public)

 apm_get_callback_proc -type type [ -package_key package_key ] \
    [ -version_id version_id ]

Return Tcl procedure name for the callback of a certain type for the given package. If no callback proc for the given type is present returns the empty string.

Switches:
-type (required)
-package_key (optional)
-version_id (optional)
Author:
Peter Marklund
See Also:

Testcases:
apm__test_callback_get_set

apm_get_installed_provides (public)

 apm_get_installed_provides -array array

Sets the dependencies provided by the packages installed on this system in an array keyed by dependency service-uri.

Switches:
-array (required)
Name of array in caller's namespace where you want this set

Testcases:
No testcase defined.

apm_get_installed_versions (public)

 apm_get_installed_versions -array array

Sets the current installed version of packages installed on this system in an array keyed by package_key.

Switches:
-array (required)
Name of array in caller's namespace where you want this set

Testcases:
files__tcl_file_syntax_errors, files__check_xql_files, files__trailing_whitespace, files__page_contracts

apm_highest_version (public)

 apm_highest_version package_key

Return the highest version of the indicated package.

Parameters:
package_key (required)
Returns:
the version_id of the highest installed version of a package.

Testcases:
No testcase defined.

apm_highest_version_name (public)

 apm_highest_version_name package_key

Return the highest version of the indicated package.

Parameters:
package_key (required)
Returns:
the version_name of the highest installed version of a package.

Testcases:
No testcase defined.

apm_instance_name_from_id (public)

 apm_instance_name_from_id package_id
Parameters:
package_id (required)
Returns:
The name of the instance.

Testcases:
No testcase defined.

apm_interface_add (public)

 apm_interface_add [ -callback callback ] \
    [ -interface_id interface_id ] version_id interface_uri \
    interface_version

Add a interface to a version.

Switches:
-callback (optional, defaults to "apm_dummy_callback")
-interface_id (optional)
Parameters:
version_id (required)
interface_uri (required)
interface_version (required)
Returns:
The id of the new interface.

Testcases:
upgrade

apm_interface_remove (public)

 apm_interface_remove interface_id

Removes a interface from the system.

Parameters:
interface_id (required)

Testcases:
No testcase defined.

apm_invoke_callback_proc (public)

 apm_invoke_callback_proc [ -proc_name proc_name ] \
    [ -version_id version_id ] [ -package_key package_key ] \
    [ -arg_list arg_list ] -type type

Invoke the Tcl callback proc of a given type for a given package version. Any errors during invocation are logged.

Switches:
-proc_name (optional)
if this is provided it is called instead of attempting to look up the proc via the package_key or version_id (needed for before-install callbacks since the db is not populated when those are called).
-version_id (optional)
-package_key (optional)
-arg_list (optional)
-type (required)
Returns:
1 if invocation was carried out successfully, 0 if no proc to invoke could be found. Will propagate any error thrown by the callback.
Author:
Peter Marklund

Testcases:
apm__test_callback_invoke

apm_load_any_changed_libraries (public)

 apm_load_any_changed_libraries [ -version_files version_files ] \
    [ errorVarName ]

In the running interpreter, reloads files marked for reload by apm_mark_version_for_reload. If any watches are set, examines watched files to see whether they need to be reloaded as well. This is intended to be called only by the request processor (since it should be invoked before any filters or registered procedures are applied).

Switches:
-version_files (optional)
Parameters:
errorVarName (optional)

Testcases:
No testcase defined.

apm_load_packages (public)

 apm_load_packages [ -force_reload ] \
    [ -load_libraries_p load_libraries_p ] \
    [ -load_queries_p load_queries_p ] [ -packages packages ]

Load Tcl libraries and queries for the packages with given keys into the current interpreter. Will load Tcl tests when the acs-automated-testing package is enabled.

Switches:
-force_reload (optional, boolean, defaults to "0")
Reload Tcl libraries even if they are already loaded.
-load_libraries_p (optional, defaults to "1")
Switch to indicate if Tcl libraries in (-procs.tcl and -init.tcl) files should be loaded. Defaults to true.
-load_queries_p (optional, defaults to "1")
Switch to indicate if xql query files should be loaded. Default true.
-packages (optional)
A list of package_keys for packages to be loaded. Defaults to all enabled packages. These packages, along with the packages they depend on, will be loaded in dependency-order using the information provided via the "provides" and "requires" definitions.
Author:
Peter Marklund
See Also:

Testcases:
No testcase defined.

apm_load_tests_p (public)

 apm_load_tests_p

Determine whether to load acs-automated-testing tests for packages.

Returns:
1 if tests should be loaded and 0 otherwise
Author:
Peter Marklund

Testcases:
No testcase defined.

apm_log (public)

 apm_log level msg

Centralized APM logging. If you want to debug the APM, change APMDebug to Debug and restart the server.

Parameters:
level (required)
msg (required)

Testcases:
No testcase defined.

apm_mark_files_for_reload (public)

 apm_mark_files_for_reload [ -force_reload ] file_list

Mark the given list of Tcl and query files for reload in all interpreters. Only marks files for reload if they haven't been loaded before or they have changed since last reload.

Switches:
-force_reload (optional, boolean)
Mark the files for reload even if their modification time in the nsv cache doesn't differ from the one in the filesystem.
Parameters:
file_list (required)
A list of paths relative to $::acs::rootdir
Returns:
The list of files marked for reload.
Author:
Peter Marklund

Testcases:
acs_sc_impl_new_from_spec

apm_mark_version_for_reload (public)

 apm_mark_version_for_reload version_id [ changed_files_var ]

Examines all tcl_procs files in package version $version_id; if any have changed since they were loaded, marks (in the apm_reload array) that they must be reloaded by each Tcl interpreter (using the apm_load_any_changed_libraries procedure).

Saves a list of files that have changed (and thus marked to be reloaded) in the variable named $file_info_var, if provided. Each element of this list is of the form: 

[list $file_id $path]

Parameters:
version_id (required)
changed_files_var (optional)

Testcases:
No testcase defined.

apm_ns_write_callback (public)

 apm_ns_write_callback string

A simple callback which prints out the log message to the server stream.

Parameters:
string (required)

Testcases:
No testcase defined.

apm_num_instances (public)

 apm_num_instances package_key
Parameters:
package_key (required)
Returns:
The number of instances of the indicated package.

Testcases:
No testcase defined.

apm_one_package_inherit_order (public)

 apm_one_package_inherit_order package_key

Returns a list of package keys in package inheritance order.

Parameters:
package_key (required)

Testcases:
No testcase defined.

apm_package_descendents (public)

 apm_package_descendents package_key

Wrapper that returns the cached package descendents list.

Parameters:
package_key (required)

Testcases:
No testcase defined.

apm_package_enabled_p (public)

 apm_package_enabled_p package_key

Returns 1 if there is an enabled package version corresponding to the package_key and 0 otherwise.

Parameters:
package_key (required)

Testcases:
No testcase defined.

apm_package_id_from_key (public)

 apm_package_id_from_key package_key
Parameters:
package_key (required)
Returns:
The package id of the instance of the package. 0 if no instance exists, error if several instances exist.

Testcases:
locale__test_system_package_setting, acs_mail_lite_inbound_procs_check, parameter_register_test, parameter__check_procs, acs_object_procs_test, logout_from_everywhere

apm_package_ids_from_key (public)

 apm_package_ids_from_key -package_key package_key [ -mounted ]
Switches:
-package_key (required)
The package key we are looking for the package
-mounted (optional, boolean)
Does the package have to be mounted?
Returns:
List of package ids of all instances of the package. Empty string

Testcases:
No testcase defined.

apm_package_inherit_order (public)

 apm_package_inherit_order package_key

Wrapper that returns the cached package inheritance order list.

Parameters:
package_key (required)

Testcases:
No testcase defined.

apm_package_installed_p (public)

 apm_package_installed_p package_key

Returns 1 if there is an installed package version corresponding to the package_key, 0 otherwise. Uses a cached value for performance.

Parameters:
package_key (required)

Testcases:
files__check_info_files

apm_package_instance_delete (public)

 apm_package_instance_delete package_id

Deletes an instance of a package

Parameters:
package_id (required)

Testcases:
No testcase defined.

apm_package_instance_new (public)

 apm_package_instance_new -package_key package_key \
    [ -instance_name instance_name ] [ -package_id package_id ] \
    [ -context_id context_id ]

Creates a new instance of a package and calls the post instantiation proc, if any. If the package is a singleton and already exists then this procedure will silently do nothing.

Switches:
-package_key (required)
The package_key of the package to instantiate.
-instance_name (optional)
The name of the package instance, defaults to the pretty name of the package type.
-package_id (optional)
The id of the new package. Optional.
-context_id (optional)
The context_id of the new package. Optional.
Returns:
The id of the instantiated package

Testcases:
test_apm_package_instance__new

apm_package_key_from_id (public)

 apm_package_key_from_id package_id
Parameters:
package_id (required)
Returns:
The package key of the instance.

Testcases:
No testcase defined.

apm_package_key_from_version_id (public)

 apm_package_key_from_version_id version_id

Returns the package_key for the given APM package version id. Goes to the database the first time called and then uses a cached value. Calls the proc apm_package_key_from_version_id_mem.

Parameters:
version_id (required)
Author:
Peter Marklund <peter@collaboraid.biz>

Testcases:
No testcase defined.

apm_package_list_url_resolution (public)

 apm_package_list_url_resolution package_list

Use a left-right, breadth-first traverse of the inheritance DAG to build a structure to be used by the request processor to resolve URLs based on a package's "extends" and "embeds" dependencies.

Parameters:
package_list (required)

Testcases:
No testcase defined.

apm_package_load_libraries_order (public)

 apm_package_load_libraries_order package_key

Wrapper that returns the cached package library load order list.

Parameters:
package_key (required)

Testcases:
apm_dependencies_api

apm_package_parameters (public)

 apm_package_parameters package_key
Parameters:
package_key (required)
Returns:
A list of all the package parameter names.

Testcases:
No testcase defined.

apm_package_registered_p (public)

 apm_package_registered_p package_key

Returns 1 if there is a registered package with the indicated package_key. Returns 0 otherwise.

Parameters:
package_key (required)

Testcases:
No testcase defined.

apm_package_rename (public)

 apm_package_rename [ -package_id package_id ] \
    -instance_name instance_name

Renames a package instance

Switches:
-package_id (optional)
-instance_name (required)

Testcases:
No testcase defined.

apm_package_supported_databases (public)

 apm_package_supported_databases package_key

Return a list of db types (i.e. oracle, postgresql) supported by the package with given key.

Parameters:
package_key (required)
Author:
Peter Marklund
See Also:

Testcases:
No testcase defined.

apm_package_url_from_id (public)

 apm_package_url_from_id package_id

Will return the first url found for a given package_id

Parameters:
package_id (required)
Returns:
The package url of the instance of the package.

Testcases:
No testcase defined.

apm_package_url_from_key (public)

 apm_package_url_from_key package_key
Parameters:
package_key (required)
Returns:
The package url of the instance of the package. only valid for singleton packages.

Testcases:
No testcase defined.

apm_package_url_resolution (public)

 apm_package_url_resolution package_key

Wrapper that returns the cached package search order list.

Parameters:
package_key (required)

Testcases:
No testcase defined.

apm_package_version_enabled_p (public)

 apm_package_version_enabled_p version_id
Parameters:
version_id (required)
Returns:
1 if the indicated package version is installed, 0 otherwise.

Testcases:
No testcase defined.

apm_package_version_installed_p (public)

 apm_package_version_installed_p package_key version_name
Parameters:
package_key (required)
version_name (required)
Returns:
1 if the indicated package version is installed, 0 otherwise.

Testcases:
No testcase defined.

apm_parameter_register (public)

 apm_parameter_register [ -callback callback ] \
    [ -parameter_id parameter_id ] [ -scope scope ] parameter_name \
    description package_key default_value datatype [ section_name ] \
    [ min_n_values ] [ max_n_values ]

Register a parameter in the system. The new "scope" parameter is named rather than positional to avoid breaking existing code.

Switches:
-callback (optional, defaults to "apm_dummy_callback")
-parameter_id (optional)
-scope (optional, defaults to "instance")
Parameters:
parameter_name (required)
description (required)
package_key (required)
default_value (required)
datatype (required)
section_name (optional)
min_n_values (optional, defaults to "1")
max_n_values (optional, defaults to "1")
Returns:
The parameter id of the new parameter.

Testcases:
test_apm_parameter__register, parameter_register_test, parameter__check_procs

apm_parameter_sync (public)

 apm_parameter_sync package_key package_id

Syncs the parameters in the database with the memory cache. This must be called after creating a new package instance.

Parameters:
package_key (required)
package_id (required)

Testcases:
No testcase defined.

apm_parameter_unregister (public)

 apm_parameter_unregister [ -callback callback ] \
    [ -package_key package_key ] [ -parameter parameter ] \
    [ -parameter_id parameter_id ] [ parameter_id_legacy ]

Unregisters a parameter from the system.

Switches:
-callback (optional, defaults to "apm_dummy_callback")
-package_key (optional)
-parameter (optional)
-parameter_id (optional)
Parameters:
parameter_id_legacy (optional)
DEPRECATED: previous versions of this proc would specify parameter_id as an unnamed argument. This has now be changed to a flag, but the old syntax is still tolerated in old code. This will generate a warning though and will be dropped in future versions.

Testcases:
parameter_register_test, parameter__check_procs

apm_parameter_update (public)

 apm_parameter_update [ -callback callback ] parameter_id package_key \
    parameter_name description default_value datatype [ section_name ] \
    [ min_n_values ] [ max_n_values ]
Switches:
-callback (optional, defaults to "apm_dummy_callback")
Parameters:
parameter_id (required)
package_key (required)
parameter_name (required)
description (required)
default_value (required)
datatype (required)
section_name (optional)
min_n_values (optional, defaults to "1")
max_n_values (optional, defaults to "1")
Returns:
The parameter id that has been updated.

Testcases:
No testcase defined.

apm_pretty_name_for_file_type (public)

 apm_pretty_name_for_file_type type

Returns the pretty name corresponding to a particular file type key

Parameters:
type (required)
Author:
Peter Marklund
See Also:

Testcases:
No testcase defined.

apm_remove_callback_proc (public)

 apm_remove_callback_proc -type type -package_key package_key

Remove the callback of a certain type for the given package.

Switches:
-type (required)
-package_key (required)
Author:
Peter Marklund

Testcases:
apm__test_callback_get_set, apm__test_callback_invoke

apm_set_callback_proc (public)

 apm_set_callback_proc [ -version_id version_id ] \
    [ -package_key package_key ] -type type proc

Set the name of an APM Tcl procedure callback for a certain package version. Checks if the callback already exists and updates if it does. If version_id is not supplied the id of the currently enabled version of the package will be used.

Switches:
-version_id (optional)
-package_key (optional)
-type (required)
Parameters:
proc (required)
Author:
Peter Marklund
See Also:

Testcases:
apm__test_callback_get_set, apm__test_callback_invoke

apm_supported_callback_types (public)

 apm_supported_callback_types

Gets the list of package callback types that are supported by the system. Each callback type represents a certain event or time when a Tcl procedure should be invoked, such as after-install

Author:
Peter Marklund

Testcases:
apm__test_info_file, apm__test_callback_get_set, apm__test_callback_invoke

apm_unused_callback_types (public)

 apm_unused_callback_types -version_id version_id

Get a list enumerating the supported callback types that are not used by the given package version.

Switches:
-version_id (required)

Testcases:
No testcase defined.

apm_version_get (public)

 apm_version_get [ -version_id version_id ] \
    [ -package_key package_key ] -array array

Gets information about a package version. TODO: Cache this proc, put it in a namespace and make sure it's used everywhere.

Switches:
-version_id (optional)
The id of the package version to get info for
-package_key (optional)
Can be specified instead of version_id in which case the live version of the package will be used.
-array (required)
The name of the array variable to upvar the info to
Author:
Peter Marklund

Testcases:
acs_system_information_api, apm_version_api

apm_version_id_from_package_key (public)

 apm_version_id_from_package_key [ -all ] package_key

Return the id of the (per default enabled) version of the given package_key. If no such version id can be found, returns the empty string.

Switches:
-all (optional, boolean)
when specified, return the enabled or disabled version_ids of the package_key.
Parameters:
package_key (required)
Returns:
the supposedly unique version_id for the enabled package, or a list of all the enabled and disabled versions when -all flag is specified
Author:
Peter Marklund

Testcases:
acs_system_information_api, apm__test_callback_get_set, apm__test_callback_invoke

apm_version_info (public)

 apm_version_info version_id

Sets a set of common package information in the caller's environment.

Parameters:
version_id (required)

Testcases:
No testcase defined.

apm_version_installed_p (public)

 apm_version_installed_p version_id
Parameters:
version_id (required)
Returns:
Returns 1 if the specified version_id is installed, 0 otherwise.

Testcases:
No testcase defined.

apm_version_load_status (public)

 apm_version_load_status version_id

If a version needs to be reloaded (i.e., a -procs.tcl has changed or been added since the version was loaded), returns "needs_reload". If the version has never been loaded, returns "never_loaded". If the version is up-to-date, returns "up_to_date".

Parameters:
version_id (required)

Testcases:
No testcase defined.

apm_version_loaded_p (public)

 apm_version_loaded_p version_id

Returns 1 if a version of a package has been loaded and initialized, or 0 otherwise.

Parameters:
version_id (required)

Testcases:
No testcase defined.
[ show source ]