- Publicity: Public Only All
site-nodes-procs.tcl
Site node API
This file defines the following Objects and Classes: ::acs::SiteNode
, ::acs::SiteNodesCache
- Location:
- packages/acs-tcl/tcl/site-nodes-procs.tcl
- Authors:
- rhs@mit.edu
- yon (yon@openforce.net), Gustaf Neumann
Procedures in this file
- Class ::acs::SiteNode (public)
- Class ::acs::SiteNodeUrlspaceCache (public)
- Class ::acs::SiteNodesCache (public)
- Object ::acs::site_node (public)
- acs::SiteNode instproc flush_cache (public)
- acs::SiteNode instproc get (public)
- acs::SiteNode instproc get_children (public)
- acs::SiteNode instproc get_package_url (public)
- acs::SiteNode instproc get_urls_from_object_id (public)
- acs::SiteNode instproc get_urls_from_package_key (public)
- acs::SiteNodeUrlspaceCache instproc flush_cache (public)
- acs::SiteNodeUrlspaceCache instproc get_node_id (public)
- acs::SiteNodesCache instproc flush_cache (public)
- acs::SiteNodesCache instproc flush_pattern (public)
- acs::SiteNodesCache instproc get_children (public)
- acs::SiteNodesCache instproc get_node_id (public)
- acs::SiteNodesCache instproc get_package_url (public)
- acs::SiteNodesCache instproc get_url (public)
- acs::SiteNodesCache instproc get_urls_from_object_id (public)
- site_node::closest_ancestor_package (public)
- site_node::delete (public)
- site_node::delete_service_nodes (public)
- site_node::exists_p (public)
- site_node::get (public)
- site_node::get_all_from_object_id (public)
- site_node::get_ancestors (public)
- site_node::get_children (public)
- site_node::get_element (public)
- site_node::get_from_node_id (public)
- site_node::get_from_object_id (public)
- site_node::get_from_url (public)
- site_node::get_node_id (public)
- site_node::get_node_id_from_object_id (public)
- site_node::get_object_id (public)
- site_node::get_package_url (public)
- site_node::get_parent (public)
- site_node::get_parent_id (public)
- site_node::get_url (public)
- site_node::get_url_from_object_id (public)
- site_node::instantiate_and_mount (public)
- site_node::mount (public)
- site_node::new (public)
- site_node::rename (public)
- site_node::unmount (public)
- site_node::update_cache (public)
- site_node::verify_folder_name (public)
Detailed information
Class ::acs::SiteNode (public)
::nx::Class ::acs::SiteNodeThis class capsulates access to site-nodes stored in the database. It is written in a style to support the needs of the traditional Tcl-based API.
- Author:
- Gustaf Neumann
- Testcases:
- No testcase defined.
Class ::acs::SiteNodeUrlspaceCache (public)
::nx::Class ::acs::SiteNodeUrlspaceCacheCache site-node information via ns_urlspace. We can use the URL trie, which supports tree match operations, for tree information. This means that for example for .vuh handlers it is not necessary to cache the full url for obtaining the site-node, like it was until now: 3839 id-/storage/view/installers/windows-installer/installer.htm 3839 id-/storage/view/aolserver/install.tgz 3839 id-/storage/view/tutorial/OpenACS_Tutorial.htm 3839 id-/storage/view/openacs-dotlrn-conference-2007-spring/Methodology_ALPE.pdf 3839 id-/storage/view/xowiki-resources/Assessment.jpg 3839 id-/storage/view/tutorial-page-map.png ... Providing a single entry like ns_urlspace set -key sitenode /storage/* 3839 is sufficient for replacing all entries above.
- Testcases:
- No testcase defined.
Class ::acs::SiteNodesCache (public)
::nx::Class ::acs::SiteNodesCacheacs::SiteNodesCache is a mixin class implementing caching of SiteNode objects. Add/remove extra caching methods as when more operations should be cached. Removing the registry of the object mixin deactivates caching for these methods completely.
- Testcases:
- No testcase defined.
Object ::acs::site_node (public)
::acs::SiteNode ::acs::site_nodeObject to interact with the ::acs::SiteNode class. The intention is to provide an API interface highly compatible with the classical OpenACS interface.
- See Also:
- ::acs::site_node get_node_id -url /value/
- ::acs::site_node flush_cache -node_id /value/ ?-with_subtree /boolean/? ?-url /value/?
- ::acs::site_node get_children -node_id /integer/ ?-all? ?-package_type /value/? ?-package_key /value/? ?-filters /value/? ?-element /value/?
- ::acs::site_node get_package_url -package_key /value/
- ::acs::site_node get_urls_from_object_id -object_id /integer/
- ::acs::site_node get_url -node_id /value/
- ::acs::site_node flush_pattern ?-partition_key /value/? /pattern/
- ::acs::site_node get ?-url /value/? ?-node_id /value/?
- ::acs::site_node get_urls_from_package_key -package_key /value/
- Testcases:
- No testcase defined.
acs::SiteNode method flush_cache (public)
<instance of acs::SiteNode> flush_cache -node_id node_id \
[ -with_subtree on|off ] [ -url url ]This is a stub method to be overloaded by some cache managers.
- Switches:
- -node_id (required)
- -with_subtree (optional, boolean)
- -url (optional)
- Testcases:
- No testcase defined.
acs::SiteNode method get (public)
<instance of acs::SiteNode> get [ -url url ] \
[ -node_id node_id ]
- Switches:
- -url (optional)
- -node_id (optional)
- Returns:
- a site node from url or site-node with all its context info
- Testcases:
- No testcase defined.
acs::SiteNode method get_children (public)
<instance of acs::SiteNode> get_children -node_id node_id \
[ -all ] [ -package_type package_type ] \
[ -package_key package_key ] [ -filters filters ] \
[ -element element ]Filtering happens here exactly like in the nsv-based version. If should be possible to realize (at least some of the) filtering via the SQL query.
- Switches:
- -node_id (required)
- -all (optional)
- -package_type (optional)
- -package_key (optional)
- -filters (optional)
- -element (optional)
- Testcases:
- No testcase defined.
acs::SiteNode method get_package_url (public)
<instance of acs::SiteNode> get_package_url \
-package_key package_key Legacy interface: previous implementations of the site-nodes assumed, that there is just one site-node entry available for a package-key. This method returns just the first answer form get_urls_from_package_key
- Switches:
- -package_key (required)
- Testcases:
- No testcase defined.
acs::SiteNode method get_urls_from_object_id (public)
<instance of acs::SiteNode> get_urls_from_object_id \
-object_id object_id Return a list of URLs for site_nodes that have the given object mounted or the empty list if there are none. The URLs are returned in descending order meaning any children will come before their parents. This ordering is useful when deleting site nodes as we must delete child site nodes before their parents.
- Switches:
- -object_id (required, integer)
- Testcases:
- No testcase defined.
acs::SiteNode method get_urls_from_package_key (public)
<instance of acs::SiteNode> get_urls_from_package_key \
-package_key package_key Return potentially multiple URLs based on a package key.
- Switches:
- -package_key (required)
- Testcases:
- No testcase defined.
acs::SiteNodeUrlspaceCache method flush_cache (public)
<instance of acs::SiteNodeUrlspaceCache> flush_cache \
-node_id node_id [ -with_subtree on|off ] [ -url url ]Cleanup in the urlspace tree: Clear always the full subtree via "-recurse" (maybe not always necessary).
- Switches:
- -node_id (required)
- -with_subtree (optional, boolean, defaults to
"true")- -url (optional)
- Testcases:
- No testcase defined.
acs::SiteNodeUrlspaceCache method get_node_id (public)
<instance of acs::SiteNodeUrlspaceCache> get_node_id -url url Get node_id for the provided URL. We have to determine the partial URL for determining the site node.
- Switches:
- -url (required)
- Returns:
- node_id (integer)
- Testcases:
- No testcase defined.
acs::SiteNodesCache method flush_cache (public)
<instance of acs::SiteNodesCache> flush_cache -node_id node_id \
[ -with_subtree on|off ] [ -url url ]Flush entries from site-node tree, including the current node, the root of flushed (sub)tree. If the node_id is not provided, or it is the node_id of root of the full site-node tree, flush the whole tree.
- Switches:
- -node_id (required)
- -with_subtree (optional, boolean, defaults to
"true")- -url (optional)
- Testcases:
- No testcase defined.
acs::SiteNodesCache method flush_pattern (public)
<instance of acs::SiteNodesCache> flush_pattern \
[ -partition_key partition_key ] patternFlush from the site-nodes caches certain information. The method hides the actual caching structure and is as well provided in conformance with the alternative implementations above. Depending on the specified pattern, it reroutes the flushing request to different caches.
- Switches:
- -partition_key (optional)
- Parameters:
- pattern (required)
- Testcases:
- No testcase defined.
acs::SiteNodesCache method get_children (public)
<instance of acs::SiteNodesCache> get_children -node_id node_id \
[ -all ] [ -package_type package_type ] \
[ -package_key package_key ] [ -filters filters ] \
[ -element element ]Cache get_children operations, except, when "-all" was specified. The underlying operation can be quite expensive, when huge site-node trees are explored. Since the argument list influences the results, we cache for every parameter combination. Since this cache contains subtrees, we have to flush trees, which is implemented via pattern flushes. So we use a separate cache to avoid long locks on site-nodes in general.
- Switches:
- -node_id (required, integer)
- -all (optional)
- -package_type (optional)
- -package_key (optional)
- -filters (optional)
- -element (optional)
- Testcases:
- No testcase defined.
acs::SiteNodesCache method get_node_id (public)
<instance of acs::SiteNodesCache> get_node_id -url url Cache the result of the upstream implementation of get_node_id in the acs::site_nodes_id_cache cache.
- Switches:
- -url (required)
- Testcases:
- No testcase defined.
acs::SiteNodesCache method get_package_url (public)
<instance of acs::SiteNodesCache> get_package_url \
-package_key package_key Cache the result of the upstream implementation of get_package_url in the acs::site_nodes_cache. Note: the cache value from the following method must currently be explicitly flushed. We do that, for instance, when we mount a new package.
- Switches:
- -package_key (required)
- Testcases:
- No testcase defined.
acs::SiteNodesCache method get_url (public)
<instance of acs::SiteNodesCache> get_url -node_id node_id It's a pain, but OpenACS and its regression test call "get_url" a few times with an empty node_id. Shortcut these calls here to avoid problems with the non-numeric partition_key.
- Switches:
- -node_id (required)
- Testcases:
- No testcase defined.
acs::SiteNodesCache method get_urls_from_object_id (public)
<instance of acs::SiteNodesCache> get_urls_from_object_id \
-object_id object_id Cache the result of the upstream implementation of get_urls_from_object_id in the acs::site_nodes_cache.
- Switches:
- -object_id (required, integer)
- Testcases:
- No testcase defined.
site_node::closest_ancestor_package (public)
site_node::closest_ancestor_package [ -url url ] [ -node_id node_id ] \
[ -package_key package_key ] [ -include_self ] \
[ -element element ]Starting with the node of the given id, or at given url, climb up the site map and return the id of the first not-null mounted object. If no ancestor object is found the empty string is returned. Will ignore itself and only return true ancestors unless
include_selfis set.
- Switches:
- -url (optional)
- The url of the node to start from. You must provide either url or node_id. An empty url is taken to mean the main site.
- -node_id (optional)
- The id of the node to start from. Takes precedence over any provided url.
- -package_key (optional)
- Restrict search to objects of this package type. You may supply a list of package_keys.
- -include_self (optional, boolean)
- Return the package_id at the passed-in node if it is of the desired package_key. Ignored if package_key is empty.
- -element (optional, defaults to
"object_id")- Returns:
- The id of the first object found and an empty string if no object is found. Throws an error if no node with given url can be found.
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_closest_ancestor_package
site_node::delete (public)
site_node::delete -node_id node_id [ -delete_subnodes ] \
[ -delete_package ]delete the site node
- Switches:
- -node_id (required)
- -delete_subnodes (optional, boolean)
- -delete_package (optional, boolean)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_update_cache, xowiki_test_cases, slot_interactions, path_resolve
site_node::delete_service_nodes (public)
site_node::delete_service_nodes -node_id node_id
Unmount and delete all (shared) service packages under this site_node.
- Switches:
- -node_id (required)
- starting node_id
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::exists_p (public)
site_node::exists_p -url url
Returns 1 if a site node exists at the given url and 0 otherwise.
- Switches:
- -url (required)
- URL path starting with a slash.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_verify_folder_name, xowiki_test_cases
site_node::get (public)
site_node::get [ -url url ] [ -node_id node_id ]
Returns an array representing the site node that matches the given url. Either url or node_id is required, if both are passed url is ignored. The array elements are: package_id, package_key, object_type, directory_p, instance_name, pattern_p, parent_id, node_id, object_id, url.
- Switches:
- -url (optional)
- -node_id (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_admin_require_site_wide, ad_context_bar, ad_context_bar_multirow, site_node_update_cache, oacs_dav_put, oacs_dav_mkcol, xowiki_test_cases
site_node::get_all_from_object_id (public)
site_node::get_all_from_object_id -object_id object_id
Return a list of site node info associated with the given object_id. The nodes will be ordered descendingly by url (children before their parents).
- Switches:
- -object_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::get_ancestors (public)
site_node::get_ancestors -node_id node_id [ -element element ]
- Switches:
- -node_id (required)
- -element (optional)
- Returns:
- the ancestors of this node
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::get_children (public)
site_node::get_children [ -all ] [ -package_type package_type ] \
[ -package_key package_key ] [ -filters filters ] \
[ -element element ] -node_id node_idThis proc gives answers to questions such as: What are all the package_id's (or any of the other available elements) for all the instances of package_key or package_type mounted under node_id xxx?
- Switches:
- Options:
- -all (optional, boolean)
- -package_type (optional)
- -package_key (optional)
- If specified, this will limit the returned nodes to those with a package of the specified package key mounted. Conflicts with the -package_type option. Can take one or more packages keys as a Tcl list.
- -filters (optional)
- Takes a list of { element value element value ... } for filtering the result list. Only nodes where element is value for each of the filters in the list will get included. For example: -filters { package_key "acs-subsite" }.
- -element (optional)
- The element of the site node you wish returned. Defaults to url, but the following elements are available: object_type, url, object_id, instance_name, package_type, package_id, name, node_id, directory_p.
- -node_id (required)
- The node for which you want to find the children.
- -all
- Set this if you want all children, not just direct children
- -package_type
- If specified, this will limit the returned nodes to those with a package of the specified package type (normally apm_service or apm_application) mounted. Conflicts with the -package_key option.
- Returns:
- A list of URLs of the site_nodes immediately under this site node, or all children, if the -all switch is specified.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_get_children, site_node_verify_folder_name
site_node::get_element (public)
site_node::get_element [ -node_id node_id ] [ -url url ] \
-element elementreturns an element from the array representing the site node that matches the given url either url or node_id is required, if both are passed url is ignored The array elements are: package_id, package_key, object_type, directory_p, instance_name, pattern_p, parent_id, node_id, object_id, url.
- Switches:
- -node_id (optional)
- -url (optional)
- -element (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_verify_folder_name
site_node::get_from_node_id (public)
site_node::get_from_node_id -node_id node_id
returns an array representing the site node for the given node_id
- Switches:
- -node_id (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::get_from_object_id (public)
site_node::get_from_object_id -object_id object_id
return the site node associated with the given object_id WARNING: Returns only the first site node associated with this object.
- Switches:
- -object_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- subsite_api
site_node::get_from_url (public)
site_node::get_from_url -url url [ -exact ]
Returns an array representing the site node that matches the given url. A trailing '/' will be appended to $url if required and not present. If the '-exact' switch is not present and $url is not found, returns the first match found by successively removing the trailing $url path component.
- Switches:
- -url (required)
- -exact (optional, boolean)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_subsite_expose_bug_1144, front_page_1, xowiki_test_cases
site_node::get_node_id (public)
site_node::get_node_id -url url
- Switches:
- -url (required)
- Returns:
- the node_id for this url
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_get_children, site_node_verify_folder_name, site_node_update_cache, site_node_closest_ancestor_package, slot_interactions, path_resolve
site_node::get_node_id_from_object_id (public)
site_node::get_node_id_from_object_id -object_id object_id
- Switches:
- -object_id (required)
- Returns:
- the site node id associated with the given object_id
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::get_object_id (public)
site_node::get_object_id -node_id node_id
- Switches:
- -node_id (required)
- Returns:
- the object_id for this node
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::get_package_url (public)
site_node::get_package_url -package_key package_key
Get the URL of any mounted instance of a package with the given package_key. If there is more than one mounted instance of a package, returns the first URL. To see all of the mounted URLs, use the site_node::get_children proc.
- Switches:
- -package_key (required)
- Returns:
- a URL, or empty string if no instance of the package is mounted.
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::get_parent (public)
site_node::get_parent -node_id node_id
- Switches:
- -node_id (required)
- Returns:
- the parent node of this node
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::get_parent_id (public)
site_node::get_parent_id -node_id node_id
- Switches:
- -node_id (required)
- Returns:
- the parent_id of this node
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::get_url (public)
site_node::get_url -node_id node_id [ -notrailing ]
return the url of this node_id
- Switches:
- -node_id (required)
- -notrailing (optional, boolean)
- If true then strip any trailing slash ('/'). This means the empty string is returned for the root.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_update_cache
site_node::get_url_from_object_id (public)
site_node::get_url_from_object_id -object_id object_id
Returns a list of URLs for site_nodes that have the given object mounted or the empty list if there are none. The url:s will be returned in descending order meaning any children will come before their parents. This ordering is useful when deleting site nodes as we must delete child site nodes before their parents.
- Switches:
- -object_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_update_cache, package_normalize_path, xowiki_test_cases, link_tests, slot_interactions, path_resolve
site_node::instantiate_and_mount (public)
site_node::instantiate_and_mount [ -node_id node_id ] \
[ -parent_node_id parent_node_id ] [ -node_name node_name ] \
[ -package_name package_name ] [ -context_id context_id ] \
-package_key package_key [ -package_id package_id ]Instantiate and mount a package of given type. Will use an existing site node if possible.
- Switches:
- -node_id (optional)
- The id of the node in the site map where the package should be mounted.
- -parent_node_id (optional)
- If no node_id is specified this will be the parent node under which the new node is created. Defaults to the main site node id.
- -node_name (optional)
- If node_id is not specified then this will be the name of the new site node that is created. Defaults to package_key.
- -package_name (optional)
- The name of the new package instance. Defaults to pretty name of package type.
- -context_id (optional)
- The context_id of the package. Defaults to the closest ancestor package in the site map.
- -package_key (required)
- The key of the package type to instantiate.
- -package_id (optional)
- The id of the new package. Optional.
- Returns:
- The id of the instantiated package
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- subsite_api, site_node_update_cache, site_node_closest_ancestor_package, ad_proc_permission_grant_and_revoke, ad_proc_permission_permission_p, test_inheritance_and_custom_permissions, fs_publish_file, xowiki_test_cases
site_node::mount (public)
site_node::mount -node_id node_id -object_id object_id \
[ -context_id context_id ]mount object at site node
- Switches:
- -node_id (required)
- -object_id (required)
- -context_id (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- ad_context_bar
site_node::new (public)
site_node::new -name name -parent_id parent_id \
[ -directory_p directory_p ] [ -pattern_p pattern_p ]Create a new site node
- Switches:
- -name (required)
- -parent_id (required)
- -directory_p (optional, defaults to
"t")- -pattern_p (optional, defaults to
"t")- Returns:
- node_id
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- ad_context_bar, site_node_closest_ancestor_package
site_node::rename (public)
site_node::rename -node_id node_id -name name
Rename the site node.
- Switches:
- -node_id (required)
- -name (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_update_cache
site_node::unmount (public)
site_node::unmount -node_id node_id
unmount an object from the site node
- Switches:
- -node_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_update_cache, xowiki_test_cases, slot_interactions, path_resolve
site_node::update_cache (public)
site_node::update_cache [ -sync_children ] -node_id node_id \
[ -url url ] [ -object_id object_id ]Brings the in-memory copy of the site nodes hierarchy in sync with the database version. Only updates the given node and its children.
- Switches:
- -sync_children (optional, boolean)
- -node_id (required)
- -url (optional)
- -object_id (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
site_node::verify_folder_name (public)
site_node::verify_folder_name -parent_node_id parent_node_id \
[ -current_node_id current_node_id ] \
[ -instance_name instance_name ] [ -folder folder ]Verifies that the given folder name is valid for a folder under the given parent_node_id. If current_node_id is supplied, it's assumed that we're renaming an existing node, not creating a new one. If folder name is not supplied, we'll generate one from the instance name, which must then be supplied.
- Switches:
- -parent_node_id (required)
- -current_node_id (optional)
- -instance_name (optional)
- -folder (optional)
- Returns:
- folder name, or empty string if the supplied folder name wasn't acceptable.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- site_node_verify_folder_name
