| Prev | Chapter 15. Kernel Documentation | Next |
|---|
User directory
Sitewide administrator directory
Subsite administrator directory
Tcl script directory
Data model
PL/SQL file
ER diagram
Transaction flow diagram
Almost all database-backed websites have users, and need to model the +
By Rafael H. Schloming and Mark Thomas
+</authorblurb> + + +User directory
Sitewide administrator directory
Subsite administrator directory
Tcl script directory
Data model
PL/SQL file
+ + +ER diagram
Transaction flow diagram
Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, particularly to support powerful subsite services; that is, where one OpenACS installation can support what appears to the user as distinct web services -for different user communities.
The primary limitation of the OpenACS 3.x user group system is that it +for different user communities.
+ +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
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 structures makes the queries over these relationships
-expensive.
In addition, the Module Scoping design in OpenACS 3.0 introduced a +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
-to:
add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption +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
group_id)
perform extra checks in Tcl and PL/SQL
functions and procedures to check both the user_id and
-group_id values
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 @@ -34,12 +82,24 @@ 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 +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 access time. The limited flexibility (no updates -on membership) trades against the complexity of the code.
The Group System data model consists of the following tables:
parties
+on membership) trades against the complexity of the code.
+The Group System data model consists of the following tables:
+ +parties
+
The set of all defined parties: any person, user, or group must have a corresponding row in this table.
persons
@@ -72,10 +132,14 @@
A mapping of a group Gto the set of groups
{Gi} that G is a component of;
this mapping includes the type of relationship by including the
-appropriaterel_id from the composition_rels table.
New groups are created through the group.new constructor.
+appropriaterel_id from the composition_rels table.
New groups are created through the group.new constructor.
When a specialized type of group is required, the group type can be extended
by an 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
+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 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.
@@ -86,9 +150,13 @@
paragraph) which watch for changes in membership or composition and update
tables that maintain the group party mappings, i.e.,
group_member_index and group_component_index. One can think
-of these tables as a manually maintained index.
The following triggers keep the group_*_index tables up to
-date:
membership_rels_in_tr
+of these tables as a manually maintained index.
+The following triggers keep the group_*_index tables up to
+date:
membership_rels_in_tr
+
Is executed when a new group/member relationship is created (an insert on
membership_rels)
membership_rels_del_tr
@@ -99,11 +167,15 @@
on composition_rels)composition_rels_del_tr
Is executed when a group/component relationship is deleted (a delete on
-composition_rels)
The data model provides the following views onto the
+composition_rels)
The data model provides the following views onto the
group_member_index and group_component_index tables. No
code outside of Groups System should modify the group_*_index
-tables.
group_member_map
+tables.
+group_member_map
+
A mapping of a party to the groups the party is a member of; this mapping
includes the type of relationship by including the appropriaterel_id
from the membership_rels table.
group_approved_member_map
@@ -129,17 +201,42 @@
A mapping of a party P to the set of parties {Pi} party P is an -approved member of.
The API consists of tables and views and PL/SQL functions. -
The group_types table is used to create new types of groups.
The group_member_map, group_approved_member_map,
+
The group_types table is used to create new types of groups.
The group_member_map, group_approved_member_map,
group_distinct_member_map, group_component_map,
party_member_map, and party_approved_member_map views are
-used to query group membership and composition.
Person
person.new creates a new person and returns the
+used to query group membership and composition.
Person
+ +person.new creates a new person and returns the
person_id. The function must be given the full name of the person in
two pieces: first_names and last_name. All other fields are
optional and default to null except for object_type which defaults
to person and creation_date which defaults to sysdate. The
-interface for this function is:
+interface for this function is: + ++ +function person.new ( person_id persons.person_id%TYPE, object_type acs_objects.object_type%TYPE, @@ -151,20 +248,34 @@ first_names persons.first_names%TYPE, last_name persons.last_name%TYPE ) return persons.person_id%TYPE; -
person.deletedeletes the person whoseperson_idis -passed to it. The interface for this procedure is:++ ++ +
person.deletedeletes the person whoseperson_idis +passed to it. The interface for this procedure is:procedure person.delete ( person_id persons.person_id%TYPE ); -
person.namereturns the name of the person whose -person_idis passed to it. The interface for this function is:++ ++ +
person.namereturns the name of the person whose +person_idis passed to it. The interface for this function is:function person.name ( person_id persons.person_id%TYPE ) return varchar; -User
acs_user.newcreates a new user and returns theuser_id. +
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 interface for this function is:
+other fields are optional. The interface for this function is: + ++ +function acs_user.new ( user_id users.user_id%TYPE, object_type acs_objects.object_type%TYPE, @@ -182,33 +293,51 @@ screen_name users.screen_name%TYPE, email_verified_p users.email_verified_p%TYPE ) return users.user_id%TYPE; -
acs_user.deletedeletes the user whoseuser_idis passed -to it. The interface for this procedure is:++ ++ +
acs_user.deletedeletes the user whoseuser_idis passed +to it. The interface for this procedure is:procedure acs_user.delete ( user_id users.user_id%TYPE ); -
acs_user.receives_alerts_preturns 't' if the user should +
acs_user.receives_alerts_p returns 't' if the user should
receive email alerts and 'f' otherwise. The interface for this
-function is:
+function is: + ++ +function acs_user.receives_alerts_p ( user_id users.user_id%TYPE ) return varchar; -Use the procedures
acs_user.approve_emailand +
Use the procedures acs_user.approve_email and
acs_user.unapprove_email to specify whether the user's email
-address is valid. The interface for these procedures are:
+address is valid. The interface for these procedures are: + ++ +procedure acs_user.approve_email ( user_id users.user_id%TYPE ); procedure acs_user.unapprove_email ( user_id users.user_id%TYPE ); -Group
acs_group.newcreates a new group and returns the +
Group
+ +acs_group.new creates a new group and returns the
group_id. All fields are optional and default to null except for
object_type which defaults to 'group',
creation_date which defaults to sysdate, and
group_name which is required. The interface for
-this function is:
+this function is: + ++ +function acs_group.new ( group_id groups.group_id%TYPE, object_type acs_objects.object_type%TYPE, @@ -219,22 +348,36 @@ url parties.url%TYPE, group_name groups.group_name%TYPE ) return groups.group_id%TYPE; -
acs_group.namereturns the name of the group whose -group_idis passed to it. The interface for this function is:++ ++ +
acs_group.namereturns the name of the group whose +group_idis passed to it. The interface for this function is:function acs_group.name ( group_id groups.group_id%TYPE ) return varchar; -
acs_group.member_preturns 't' if the specified party is +
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:
+for this function is: + ++ +function acs_group.member_p ( group_id groups.group_id%TYPE, party_id parties.party_id%TYPE, ) return char; -Membership Relationship
membership_rel.newcreates a new membership relationship type +
Membership Relationship
+ +membership_rel.new creates a new membership relationship type
between two parties and returns the relationship type's rel_id.
All fields are optional and default to null except for rel_type
-which defaults to membership_rel. The interface for this function is:
+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, @@ -244,43 +387,73 @@ creation_user acs_objects.creation_user%TYPE, creation_ip acs_objects.creation_ip%TYPE, ) return membership_rels.rel_id%TYPE; -
membership_rel.bansets themember_stateof the given -rel_idto 'banned'. The interface for this procedure is:++ ++ +
membership_rel.bansets themember_stateof the given +rel_idto 'banned'. The interface for this procedure is:procedure membership_rel.ban ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.approvesets themember_stateof the +
membership_rel.approve sets the member_state of the
given rel_id to 'approved'. The interface for this procedure
-is:
+is: + ++ +procedure membership_rel.approve ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.rejectsets themember_stateof the given -rel_idto 'rejected. The interface for this procedure is:++ ++ +
membership_rel.rejectsets themember_stateof the given +rel_idto 'rejected. The interface for this procedure is:procedure membership_rel.reject ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.unapprovesets themember_stateof the +
membership_rel.unapprove sets the member_state of the
given rel_id to an empty string ''. The interface for this
-procedure is:
+procedure is: + ++ +procedure membership_rel.unapprove ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.deletedsets themember_stateof the +
membership_rel.deleted sets the member_state of the
given rel_id to 'deleted'. The interface for this procedure
-is:
+is: + ++ +procedure membership_rel.deleted ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.deletedeletes the givenrel_id. The -interface for this procedure is:++ ++ +
membership_rel.deletedeletes the givenrel_id. The +interface for this procedure is:procedure membership_rel.delete ( rel_id membership_rels.rel_id%TYPE ); -Composition Relationship
composition_rel.newcreates a new composition relationship type +
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 for rel_type which defaults to
-composition_rel. The interface for this function is:
+composition_rel. The interface for this function is: + +function membership_rel.new ( rel_id composition_rels.rel_id%TYPE, rel_type acs_rels.rel_type%TYPE, @@ -289,19 +462,78 @@ creation_user acs_objects.creation_user%TYPE, creation_ip acs_objects.creation_ip%TYPE, ) return composition_rels.rel_id%TYPE; -
composition_rel.deletedeletes the givenrel_id. The -interface for this procedure is:++ ++ +
composition_rel.deletedeletes the givenrel_id. The +interface for this procedure is:procedure membership_rel.delete ( rel_id composition_rels.rel_id%TYPE ); -
Mark Thomas
| Document Revision # | Action Taken, Notes | When? | By Whom? | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0.1 | Creation | 08/22/2000 | Rafael H. Schloming | ||||||||||||||||
| 0.2 | Initial Revision | 08/30/2000 |
+ Mark Thomas
+
+
+
+
+
|