• Publicity: Public Only All

site-nodes-procs.tcl

Site node API

This file defines the following Objects and Classes: ::acs::SiteNode[i], ::acs::SiteNodeUrlspaceCache[i], ::acs::SiteNodesCache[i], ::acs::site_node[i], ::acs::SiteNode[i], ::acs::SiteNode[i], ::acs::SiteNodesCache[i], ::acs::SiteNode[i], ::acs::SiteNodesCache[i], ::acs::SiteNodesCache[i], ::acs::SiteNode[i], ::acs::SiteNodesCache[i], ::acs::SiteNode[i], ::acs::SiteNode[i], ::acs::SiteNodesCache[i], ::acs::SiteNode[i], ::acs::SiteNode[i], ::acs::SiteNode[i], ::acs::SiteNode[i], ::acs::SiteNode[i], ::acs::SiteNode[i], ::acs::SiteNodeUrlspaceCache[i], ::acs::SiteNodeUrlspaceCache[i], ::acs::SiteNodesCache[i], ::acs::SiteNodesCache[i], ::acs::SiteNodesCache[i], ::acs::SiteNodesCache[i], ::acs::SiteNodesCache[i], ::acs::SiteNodesCache[i], ::acs::SiteNodesCache[i]

Location:
packages/acs-tcl/tcl/site-nodes-procs.tcl
Authors:
rhs@mit.edu
yon (yon@openforce.net), Gustaf Neumann

Procedures in this file

Detailed information

Class ::acs::SiteNode (public)

 ::nx::Class ::acs::SiteNode[i]

This 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::SiteNodeUrlspaceCache[i]

Cache 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::SiteNodesCache[i]

acs::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_node[i]

Object to interact with the ::acs::SiteNode class. The intention is to provide an API interface highly compatible with the classical OpenACS interface.

See Also:

Testcases:
No testcase defined.

acs::SiteNode method flush_cache (public)

 <instance of acs::SiteNode[i]> 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[i]> 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[i]> 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[i]> 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[i]> 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[i]> 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[i]> 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[i]> 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[i]> 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[i]> flush_pattern \
    [ -partition_key partition_key ] pattern

Flush 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[i]> 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[i]> 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[i]> 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[i]> 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[i]> 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_self is 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

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)

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

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.

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)

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)

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

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_id

This 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:
-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.
Options:
-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.

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 element

returns 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:

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:

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)

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:

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

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

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

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:

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

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

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.

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)

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

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)

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

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)

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)

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)

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.

Testcases:
site_node_verify_folder_name
[ show source ]