Index: openacs-4/packages/acs-core-docs/www/groups-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.adp,v diff -u -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/groups-design.adp 9 Jun 2016 08:44:49 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/groups-design.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -34,19 +34,19 @@
The primary limitation of the OpenACS 3.x user group system is
-that it restricts the application developer to representing a "flat
-group" that contains only users: The user_groups
table may contain the
+that it restricts the application developer to representing a
+"flat group" that contains only users: The user_groups
table may contain the
group_id
of a parent group, but
parent-child relationship support is limited because it only allows
one kind of relationship between groups to be represented.
-Moreover, the Oracle database's limited support for tree-like
+Moreover, the Oracle database's limited support for tree-like
structures makes the queries over these relationships
expensive.
In addition, the Module Scoping design in OpenACS 3.0 introduced
a party abstraction - a
thing that is a person or a group of people - though not in the
form of an explicit table. Rather, the triple of scope
, user_id
, and group_id
columns was used to identify the
party. One disadvantage of this design convention is that it
-increases a data model's complexity by requiring the programmer
+increases a data model's complexity by requiring the programmer
to:
add these three columns to each "scoped" table
define a multi-column check constraint to protect against data
corruption (e.g., a row with a scope
value of "group" but a null
@@ -60,16 +60,16 @@
The core of the Group Systems data model is quite simple, but it -was designed in the hopes of modeling "real world" organizations -which can be complex graph structures. The Groups System only -considers groups that can be modeled using directed acyclic graphs, -but queries over these structures are still complex enough to slow -the system down. Since almost every page will have at least one -membership check, a number of triggers, views, and auxiliary tables -have been created in the hopes of increasing performance. To keep -the triggers simple and the number of triggers small, the data -model disallows updates on the membership and composition tables, -only inserts and deletes are permitted.
The data model has tried to balance the need to model actual +was designed in the hopes of modeling "real world" +organizations which can be complex graph structures. The Groups +System only considers groups that can be modeled using directed +acyclic graphs, but queries over these structures are still complex +enough to slow the system down. Since almost every page will have +at least one membership check, a number of triggers, views, and +auxiliary tables have been created in the hopes of increasing +performance. To keep the triggers simple and the number of triggers +small, the data model disallows updates on the membership and +composition tables, only inserts and deletes are permitted.
The data model has tried to balance the need to model actual organizations without making the system too complex or too slow. The added triggers, views, and tables and will increase storage requirements and the insert and delete times in an effort to speed @@ -82,8 +82,9 @@
parties
The set of all defined parties: any person, user, or group must have a corresponding row in this table.
persons
The set of all defined persons. To allow easy sorting of
persons, the name requirement 30.10 is
-met by splitting the person's name into two columns: first_names
and last_name
.
users
The set of all registered users; this table includes information
-about the user's email address and the user's visits to the
+met by splitting the person's name into two columns:
+first_names
and last_name
.
users
The set of all registered users; this table includes information +about the user's email address and the user's visits to the site.
user_preferences
Preferences for the user.
groups
The set of all defined groups.
group_types
When a new type of group is created, this table holds additional knowledge level attributes for the group and its subtypes.
membership_rels
The set of direct membership relationships between a group and a party.
group_member_index
A mapping of a party P to the groups {Gi @@ -104,10 +105,10 @@ application developer. Membership constraints can be specified at creation time by passing a parent group to the constructor.
The membership_rels
and
composition_rels
tables
-indicate a group's direct members and direct components; these
+indicate a group's direct members and direct components; these
tables do not provide a record of the members or components that
are in the group by virtue of being a member or component of one of
-the group's component groups. Site pages will query group
+the group's component groups. Site pages will query group
membership often, but the network of component groups can become a
very complex directed acyclic graph and traversing this graph for
every query will quickly degrade performance. To make membership
@@ -130,10 +131,8 @@
appropriaterel_id
from the
membership_rels
table.
group_approved_member_map
A mapping of a party to the groups the party is an approved
member of (member_state
is
-'approved'); this mapping includes the type of relationship by
-including the appropriaterel_id
-from the membership_rels
-table.
group_distinct_member_map
A person may appear in the group member map multiple times, for
+'approved'); this mapping includes the type of relationship
+by including the appropriaterel_id
from the membership_rels
table.
group_distinct_member_map
A person may appear in the group member map multiple times, for example, by being a member of two different groups that are both components of a third group. This view is strictly a mapping of approved members to @@ -201,8 +200,8 @@
User
acs_user.new
creates a new
user and returns the user_id
.
-The function must be given the user's email address and the full
-name of the user in two pieces: first_names
and last_name
. All other fields are optional.
+The function must be given the user's email address and the
+full name of the user in two pieces: first_names
and last_name
. All other fields are optional.
The interface for this function is:
function acs_user.new ( user_id users.user_id%TYPE, @@ -230,13 +229,13 @@ );
acs_user.receives_alerts_p
-returns 't' if the user should receive email alerts and 'f'
-otherwise. The interface for this function is:
+returns 't' if the user should receive email alerts and +'f' otherwise. The interface for this function is:function acs_user.receives_alerts_p ( user_id users.user_id%TYPE ) return varchar;Use the procedures
acs_user.approve_email
andacs_user.unapprove_email
to specify whether -the user's email address is valid. The interface for these +the user's email address is valid. The interface for these procedures are:procedure acs_user.approve_email ( user_id users.user_id%TYPE @@ -248,10 +247,11 @@Group
acs_group.new
creates a new group and returns thegroup_id
. -All fields are optional and default to null except forobject_type
which defaults to 'group', -creation_date
which defaults to -sysdate
, andgroup_name
which is required. The interface -for this function is:+All fields are optional and default to null except forobject_type
which defaults to +'group',creation_date
+which defaults tosysdate
, and +group_name
which is required. +The interface for this function is:function acs_group.new ( group_id groups.group_id%TYPE, object_type acs_objects.object_type%TYPE, @@ -271,8 +271,9 @@ ) return varchar;
acs_group.member_p
returns -'t' if the specified party is a member of the specified group. -Returns 'f' otherwise. The interface for this function is:+'t' if the specified party is a member of the specified +group. Returns 'f' otherwise. The interface for this +function is:function acs_group.member_p ( group_id groups.group_id%TYPE, party_id parties.party_id%TYPE, @@ -281,9 +282,10 @@ Relationship
membership_rel.new
creates a new membership relationship type between two parties and returns -the relationship type'srel_id
. -All fields are optional and default to null except forrel_type
which defaults to membership_rel. -The interface for this function is:+the relationship type'srel_id
. All fields are optional and default +to null except forrel_type
+which defaults to membership_rel. The interface for this function +is:function membership_rel.new ( rel_id membership_rels.rel_id%TYPE, rel_type acs_rels.rel_type%TYPE, @@ -304,8 +306,8 @@
membership_rel.approve
sets themember_state
of the given -rel_id
to 'approved'. The -interface for this procedure is:+rel_id
to 'approved'. +The interface for this procedure is:procedure membership_rel.approve ( rel_id membership_rels.rel_id%TYPE ); @@ -328,8 +330,8 @@
membership_rel.deleted
sets themember_state
of the given -rel_id
to 'deleted'. The -interface for this procedure is:+rel_id
to 'deleted'. +The interface for this procedure is:procedure membership_rel.deleted ( rel_id membership_rels.rel_id%TYPE ); @@ -343,9 +345,9 @@Composition Relationship
composition_rel.new
creates -a new composition relationship type and returns the relationship's -rel_id
. All fields are optional -and default to null except forrel_type
which defaults to composition_rel. +a new composition relationship type and returns the +relationship'srel_id
. All +fields are optional and default to null except forrel_type
which defaults to composition_rel. The interface for this function is:function membership_rel.new ( rel_id composition_rels.rel_id%TYPE,