Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -r1.34.2.1 -r1.34.2.2 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 9 Jun 2016 08:44:50 -0000 1.34.2.1 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 23 Jun 2016 08:32:45 -0000 1.34.2.2 @@ -20,7 +20,7 @@ data model that keeps track of the application objects that we wish to manage, and serves as a primary store of metadata. By metadata, we mean data stored on behalf of an application -outside of the application's data model in order to enable +outside of the application's data model in order to enable certain central services. The OpenACS 4 Object Model (or object system) manages several different kinds of data and metadata to allow us to provide general services to applications:

Summary and Design Considerations

The OpenACS 4 Object Model is designed to generalize and unify the following mechanisms that are repeatedly implemented in OpenACS-based systems to manage generic and application specific metadata:

Why not Object Databases?

The presence of a framework for subtyping and inheritance always brings up -the question of why we don't just use an object database. The main reason +the question of why we don't just use an object database. The main reason is that all of the major object database vendors ship products that are effectively tied to some set of object oriented programming languages. Their idea is to provide tight language-level integration to lower the @@ -235,7 +235,7 @@ the relational data model while gaining the object oriented features we need most.

In the context of OpenACS 4, this means using the object model to make our data models more flexible, so that new modules can easily gain access to -generic features. However, while the API itself doesn't enforce the idea +generic features. However, while the API itself doesn't enforce the idea that applications only use the object model for metadata, it is also the case that the data model is not designed to scale to large type hierarchies. In the more limited domain of the metadata model, this is acceptable since the @@ -319,7 +319,7 @@ by the table_name of the corresponding object type, although, as mentioned above, we sometimes store attribute values as key-value pairs in a "skinny" table. However, when you ask the question "What are -the attributes of this type of object?", you don't really care about +the attributes of this type of object?", you don't really care about how the values for each attribute are stored (in a column or as key-value pairs); you expect to receive the complete list of all attributes.

  • The max_n_values and min_n_values columns encode information about the number of values an attribute may hold. @@ -370,7 +370,7 @@ model, which is discussed next.

    • Operational-level Data Model

    The operational level data model centers around the acs_objects table. This table contains a single row for every instance of the type acs_object. The table contains the -object's unique identifier, a reference to its type, security +object's unique identifier, a reference to its type, security information, and generic auditing information. Here is what the table looks like:

     
@@ -395,10 +395,10 @@
 acs_object_context_index that stores the context hierarchy.
    Other tables in the core data model store additional information related
 to objects. The table acs_attribute_values and
 acs_static_attr_values are used to store attribute values that
-are not stored in a helper table associated with the object's type. The
+are not stored in a helper table associated with the object's type. The
 former is used for instance attributes while the latter is used for
 class-wide "static" values. These tables have the same basic form,
-so we'll only show the first:
    +so we'll only show the first:
     
 create table acs_attribute_values (
         object_id       not null
@@ -431,8 +431,8 @@
 type. We do this so we can store all the mapping tables in this one
 table.
  • rel_type is the ID of the relation type to which this object
 belongs.
  • The next two object IDs are the IDs of the objects being mapped.

    • All this table does is store one row for every pair of objects that -we'd like to attach with a relation. Any additional attributes that -we'd like to attach to this pair of objects is specified in the +we'd like to attach with a relation. Any additional attributes that +we'd like to attach to this pair of objects is specified in the attributes of the relation type, and could be stored in any number of places. As in the 3.x user/groups system, these places include helper tables or generic skinny tables.

    This table, along with acs_attributes and @@ -444,9 +444,9 @@ the system. Services can use this table along with the metadata in stored in the knowledge level data model to create, manage, query and manipulate objects in a uniform manner. The acs_rels table has an analogous -role in storing information on relations.

    These are all the tables that we'll discuss in this document. The rest +role in storing information on relations.

    These are all the tables that we'll discuss in this document. The rest of the Kernel data model is described in the documents for subsites, the permissions system and for the groups system.

    Some examples of how these tables are used in the system can be found in -the discussion of the API, which comes next.

    API

    Now we'll examine each piece of the API in detail. Bear in mind that +the discussion of the API, which comes next.

    API

    Now we'll examine each piece of the API in detail. Bear in mind that the Object Model API is defined primarily through PL/SQL packages.

    Object Types and Attributes

    The object system provides an API for creating new object types and then attaching attributes to them. The procedures create_type and drop_type are used to create and delete type definitions.

    The two calls show up in the package acs_object_type.

    @@ -578,7 +578,7 @@
 with the data model at a lower level.
    The function acs_object.new() makes a new object for you. The
 function acs_object.del() deletes an object. As before, this
 is an abbreviated interface with all the long type specs removed. See the
-data model or developer's guide for the full interface.
    +data model or developer's guide for the full interface.
     
  function new (
   object_id     in acs_objects.object_id%TYPE default null,
@@ -599,8 +599,8 @@
 
 
    Next, we define some generic functions to manipulate attributes. Again,
 these interfaces are useful to an extent, but for large scale queries,
-it's likely that developers would have to query the data model directly,
-and then encapsulate their queries in procedures.
    For names, the default_name function is used if you don't
+it's likely that developers would have to query the data model directly,
+and then encapsulate their queries in procedures.
    For names, the default_name function is used if you don't
 want to define your own name function.
     
  function name (
@@ -667,7 +667,7 @@
 
 
 
    This function will typically be defined in the context of a PL/SQL
-package, but we've left it stand-alone here for simplicity.
    To summarize: in order to take advantage of OpenACS 4 services, a new
+package, but we've left it stand-alone here for simplicity.
    To summarize: in order to take advantage of OpenACS 4 services, a new
 application need only do three things:
    • Define a data model to describe application objects. This can just be a
 normal SQL table.
    • Create an object type, using code like in the example from the previous
 section.
    • Make sure application objects are created using
@@ -776,9 +776,9 @@
  );
 
 
-
    In this example, we've made groups a subtype of
+

    In this example, we've made groups a subtype of acs_object to make the code simpler. The actual data model is -somewhat different. Also, we've assumed that there is a helper table +somewhat different. Also, we've assumed that there is a helper table called groups to store information on groups, and that there is a helper table called group_types that has been defined to store extra attributes on groups.

    Now, assuming we have another object type called person to @@ -851,7 +851,7 @@ end; -

    Summary and Discussion

    The Object Model's API and data model provides a small set of simple +

    Summary and Discussion

    The Object Model's API and data model provides a small set of simple procedures that allow applications to create object types, object instances, and object relations. Most of the data model is straightforward; the relation type mechanism is a bit more complex, but in return it provides functionality