Initial Import

acs-reference.info

+<?xml version="1.0"?>
+<!-- Generated by the OpenACS Package Manager -->
+
+<package key="acs-reference" url="http://www.arsdigita.com/acs-repository/apm/packages/acs-reference" type="apm_service">
+    <package-name>ACS Reference Data</package-name>
+    <pretty-plural>ACS Reference Datas</pretty-plural>
+    <initial-install-p>t</initial-install-p>
+    <singleton-p>t</singleton-p>
+
+    <version name="5.1.5" url="http://openacs.org/repository/download/apm/acs-reference-5.1.5.apm">
+        <owner url="mailto:jon@jongriffin.com">Jon Griffin</owner>
+        <summary>Tools and API for managing refrence data.</summary>
+        <release-date>2004-02-28</release-date>
+        <maturity>3</maturity>
+        <vendor url="http://www.mayuli.com">Mayuli Enterprises, LLC</vendor>
+        <description format="text/html">Reference Data provides an API to support:
+&lt;ul&gt;
+&lt;li&gt; A common set of reference data.
+&lt;li&gt; Running standard reports on this data.
+&lt;li&gt; Monitoring the usage of reference data.
+&lt;/ul&gt;</description>
+        <provides url="acs-reference" version="5.1.4"/>
+        <requires url="acs-kernel" version="5.0.0"/>
+
+        <callbacks>
+        </callbacks>
+        <parameters>
+        <!-- No version parameters -->
+        </parameters>
+
+    </version>
+</package>
+
+
+
+

sql/oracle/acs-reference-create.sql

+--
+-- packages/acs-reference/sql/acs-reference-create.sql
+--
+-- @author jon@arsdigita.com
+-- @creation-date 2000-11-21
+-- @cvs-id $Id$
+
+-- setup the basic admin privileges
+
+begin 
+    acs_privilege.create_privilege('acs_reference_create');
+    acs_privilege.create_privilege('acs_reference_write');
+    acs_privilege.create_privilege('acs_reference_read');
+    acs_privilege.create_privilege('acs_reference_delete');
+    
+    acs_privilege.add_child('create','acs_reference_create');
+    acs_privilege.add_child('write', 'acs_reference_write');
+    acs_privilege.add_child('read',  'acs_reference_read');
+    acs_privilege.add_child('delete','acs_reference_delete');
+end;
+/
+show errors
+
+-- Create the basic object type used to represent a reference database
+
+begin
+    acs_object_type.create_type (
+        supertype     => 'acs_object',
+        object_type   => 'acs_reference_repository',
+        pretty_name   => 'ACS Reference Repository',
+        pretty_plural => 'ACS Reference Repositories', 
+        table_name    => 'acs_reference_repositories',
+        id_column     => 'repository_id',
+        name_method   => 'acs_object.default_name'
+);
+end;
+/
+show errors
+
+-- A table to store metadata for each reference database
+
+create table acs_reference_repositories (
+    repository_id	integer
+			constraint arr_repository_id_fk references acs_objects (object_id)
+			constraint arr_repository_id_pk primary key,
+    -- what is the table name we are monitoring
+    table_name		varchar2(100)  
+			constraint arr_table_name_nn not null
+			constraint arr_table_name_uq unique,
+    -- is this external or internal data
+    internal_data_p     char(1)       
+			constraint arr_internal_data_p_ck
+        		check (internal_data_p in ('t','f')),
+    -- Does this source include pl/sql package?
+    package_name	varchar2(100)
+			constraint arr_package_name_uq unique,
+    -- last updated
+    last_update		date,
+    -- where is this data from
+    source		varchar2(1000),
+    source_url		varchar2(255),
+    -- should default to today
+    effective_date	date default sysdate,
+    expiry_date		date,
+    -- a text field to hold the maintainer
+    maintainer_id	integer
+			constraint arr_maintainer_id_fk references persons(person_id),
+    -- this could be ancillary docs, pdf's etc
+    notes blob
+);
+
+-- API
+
+create or replace package acs_reference
+as
+    function new (
+        repository_id   in acs_reference_repositories.repository_id%TYPE default null,
+        table_name      in acs_reference_repositories.table_name%TYPE,
+        internal_data_p in acs_reference_repositories.internal_data_p%TYPE default 'f',
+        package_name    in acs_reference_repositories.package_name%TYPE default null,
+        last_update     in acs_reference_repositories.last_update%TYPE default sysdate,
+        source          in acs_reference_repositories.source%TYPE default null,
+        source_url      in acs_reference_repositories.source_url%TYPE default null,
+        effective_date  in acs_reference_repositories.effective_date%TYPE default sysdate,
+        expiry_date     in acs_reference_repositories.expiry_date%TYPE default null,
+        notes           in acs_reference_repositories.notes%TYPE default empty_blob(), 
+        creation_date   in acs_objects.creation_date%TYPE default sysdate,
+        creation_user   in acs_objects.creation_user%TYPE default null,
+        creation_ip     in acs_objects.creation_ip%TYPE default null,
+        object_type     in acs_objects.object_type%TYPE default 'acs_reference_repository',
+        first_names     in persons.first_names%TYPE default null,
+        last_name       in persons.last_name%TYPE default null
+    ) return acs_objects.object_id%TYPE;
+
+    procedure del (
+        repository_id in acs_reference_repositories.repository_id%TYPE
+    );
+
+    function is_expired_p (
+	repository_id integer
+    ) return char;
+
+ end acs_reference;
+/
+show errors
+
+
+create or replace package body acs_reference
+as
+    function new (
+        repository_id   in acs_reference_repositories.repository_id%TYPE default null,
+        table_name      in acs_reference_repositories.table_name%TYPE,
+        internal_data_p in acs_reference_repositories.internal_data_p%TYPE default 'f',
+        package_name    in acs_reference_repositories.package_name%TYPE default null,
+        last_update     in acs_reference_repositories.last_update%TYPE default sysdate,
+        source          in acs_reference_repositories.source%TYPE default null,
+        source_url      in acs_reference_repositories.source_url%TYPE default null,
+        effective_date  in acs_reference_repositories.effective_date%TYPE default sysdate,
+        expiry_date     in acs_reference_repositories.expiry_date%TYPE default null,
+        notes           in acs_reference_repositories.notes%TYPE default empty_blob(), 
+        creation_date   in acs_objects.creation_date%TYPE default sysdate,
+        creation_user   in acs_objects.creation_user%TYPE default null,
+        creation_ip     in acs_objects.creation_ip%TYPE default null,
+        object_type     in acs_objects.object_type%TYPE default 'acs_reference_repository',
+        first_names     in persons.first_names%TYPE default null,
+        last_name       in persons.last_name%TYPE default null
+    ) return acs_objects.object_id%TYPE
+    is
+        v_repository_id acs_reference_repositories.repository_id%TYPE;
+        v_maintainer_id persons.person_id%TYPE;
+    begin
+        v_repository_id := acs_object.new (
+             object_id     => repository_id,
+             creation_date => creation_date,
+             creation_user => creation_user,
+             creation_ip   => creation_ip,
+             object_type   => object_type
+        );
+
+	if first_names is not null and last_name is not null then
+            v_maintainer_id := person.new (
+	         first_names   => first_names,
+	         last_name     => last_name,
+		 email         => null
+            );
+	else
+	    v_maintainer_id := null;
+	end if;
+
+        insert into acs_reference_repositories
+            (repository_id, 
+             table_name,
+             internal_data_p,
+             last_update,
+             package_name,
+             source, 
+             source_url,
+             effective_date,
+             expiry_date,
+             maintainer_id,
+             notes)
+        values 
+            (v_repository_id, 
+             table_name,
+             internal_data_p,
+             last_update,
+             package_name,
+             source, 
+             source_url,
+             effective_date,
+             expiry_date,
+             v_maintainer_id,
+             notes);
+        return v_repository_id;    
+    end new;
+
+    procedure del (
+        repository_id in acs_reference_repositories.repository_id%TYPE
+    )
+    is
+	v_maintainer_id integer;
+    begin
+	select maintainer_id into v_maintainer_id
+	from   acs_reference_repositories
+	where  repository_id = acs_reference.del.repository_id;
+
+        delete from acs_reference_repositories
+        where  repository_id = acs_reference.del.repository_id;
+
+        acs_object.del(repository_id);
+	person.del(v_maintainer_id);
+
+    end del;
+
+    function is_expired_p (
+	repository_id integer
+    ) return char
+    is
+	v_expiry_date date;
+    begin
+	select expiry_date into v_expiry_date
+	from   acs_reference_repositories
+	where  repository_id = is_expired_p.repository_id;
+
+	if nvl(v_expiry_date,sysdate+1) < sysdate then
+	    return 't';
+	else
+	    return 'f';
+	end if;
+    end;	    
+
+end acs_reference;
+/
+show errors

sql/oracle/acs-reference-drop.sql

+-- Drop the ACS Reference packages
+--
+-- @author jon@jongriffin.com
+-- @cvs-id $Id$
+
+set serveroutput on
+
+-- drop all associated tables and packages
+-- ordered by repository_id for dependencies.
+
+declare
+    cursor refsrc_cur is
+	 select   table_name,
+                  package_name,
+                  repository_id
+	 from     acs_reference_repositories
+         order by repository_id desc;
+begin
+    for rec in refsrc_cur loop
+	 dbms_output.put_line('Dropping ' || rec.table_name);
+	 execute immediate 'drop table ' || rec.table_name;
+	 if rec.package_name is not null then
+	     execute immediate 'drop package ' || rec.package_name;
+         end if;
+         acs_reference.del(rec.repository_id);
+    end loop;
+end;
+/
+show errors
+
+-- drop privileges
+begin
+    acs_privilege.remove_child('create','acs_reference_create');
+    acs_privilege.remove_child('write', 'acs_reference_write');
+    acs_privilege.remove_child('read',  'acs_reference_read');
+    acs_privilege.remove_child('delete','acs_reference_delete');
+
+    acs_privilege.drop_privilege('acs_reference_create');
+    acs_privilege.drop_privilege('acs_reference_write');
+    acs_privilege.drop_privilege('acs_reference_read');
+    acs_privilege.drop_privilege('acs_reference_delete');
+end;
+/
+show errors
+
+-- drop the object
+
+begin
+    acs_object_type.drop_type('acs_reference_repository','t');
+end;
+/
+show errors
+  
+drop package acs_reference;
+drop table   acs_reference_repositories;
+

sql/oracle/upgrade/upgrade-0.2d-0.3d.sql

+--
+-- packages/acs-reference/sql/acs-reference-create.sql
+--
+-- @author jon@arsdigita.com
+-- @creation-date 2000-11-21
+-- @cvs-id $Id$
+
+
+create or replace package acs_reference
+as
+    function new (
+        repository_id   in acs_reference_repositories.repository_id%TYPE default null,
+        table_name      in acs_reference_repositories.table_name%TYPE,
+        internal_data_p in acs_reference_repositories.internal_data_p%TYPE default 'f',
+        package_name    in acs_reference_repositories.package_name%TYPE default null,
+        last_update     in acs_reference_repositories.last_update%TYPE default sysdate,
+        source          in acs_reference_repositories.source%TYPE default null,
+        source_url      in acs_reference_repositories.source_url%TYPE default null,
+        effective_date  in acs_reference_repositories.effective_date%TYPE default sysdate,
+        expiry_date     in acs_reference_repositories.expiry_date%TYPE default null,
+        notes           in acs_reference_repositories.notes%TYPE default empty_blob(), 
+        creation_date   in acs_objects.creation_date%TYPE default sysdate,
+        creation_user   in acs_objects.creation_user%TYPE default null,
+        creation_ip     in acs_objects.creation_ip%TYPE default null,
+        object_type     in acs_objects.object_type%TYPE default 'acs_reference_repository',
+        first_names     in persons.first_names%TYPE default null,
+        last_name       in persons.last_name%TYPE default null
+    ) return acs_objects.object_id%TYPE;
+
+    procedure del (
+        repository_id in acs_reference_repositories.repository_id%TYPE
+    );
+
+    function is_expired_p (
+	repository_id integer
+    ) return char;
+
+ end acs_reference;
+/
+show errors
+
+
+create or replace package body acs_reference
+as
+    function new (
+        repository_id   in acs_reference_repositories.repository_id%TYPE default null,
+        table_name      in acs_reference_repositories.table_name%TYPE,
+        internal_data_p in acs_reference_repositories.internal_data_p%TYPE default 'f',
+        package_name    in acs_reference_repositories.package_name%TYPE default null,
+        last_update     in acs_reference_repositories.last_update%TYPE default sysdate,
+        source          in acs_reference_repositories.source%TYPE default null,
+        source_url      in acs_reference_repositories.source_url%TYPE default null,
+        effective_date  in acs_reference_repositories.effective_date%TYPE default sysdate,
+        expiry_date     in acs_reference_repositories.expiry_date%TYPE default null,
+        notes           in acs_reference_repositories.notes%TYPE default empty_blob(), 
+        creation_date   in acs_objects.creation_date%TYPE default sysdate,
+        creation_user   in acs_objects.creation_user%TYPE default null,
+        creation_ip     in acs_objects.creation_ip%TYPE default null,
+        object_type     in acs_objects.object_type%TYPE default 'acs_reference_repository',
+        first_names     in persons.first_names%TYPE default null,
+        last_name       in persons.last_name%TYPE default null
+    ) return acs_objects.object_id%TYPE
+    is
+        v_repository_id acs_reference_repositories.repository_id%TYPE;
+        v_maintainer_id persons.person_id%TYPE;
+    begin
+        v_repository_id := acs_object.new (
+             object_id     => repository_id,
+             creation_date => creation_date,
+             creation_user => creation_user,
+             creation_ip   => creation_ip,
+             object_type   => object_type
+        );
+
+	if first_names is not null and last_name is not null then
+            v_maintainer_id := person.new (
+	         first_names   => first_names,
+	         last_name     => last_name,
+		 email         => null
+            );
+	else
+	    v_maintainer_id := null;
+	end if;
+
+        insert into acs_reference_repositories
+            (repository_id, 
+             table_name,
+             internal_data_p,
+             last_update,
+             package_name,
+             source, 
+             source_url,
+             effective_date,
+             expiry_date,
+             maintainer_id,
+             notes)
+        values 
+            (v_repository_id, 
+             table_name,
+             internal_data_p,
+             last_update,
+             package_name,
+             source, 
+             source_url,
+             effective_date,
+             expiry_date,
+             v_maintainer_id,
+             notes);
+        return v_repository_id;    
+    end new;
+
+    procedure del (
+        repository_id in acs_reference_repositories.repository_id%TYPE
+    )
+    is
+	v_maintainer_id integer;
+    begin
+	select maintainer_id into v_maintainer_id
+	from   acs_reference_repositories
+	where  repository_id = acs_reference.del.repository_id;
+
+        delete from acs_reference_repositories
+        where  repository_id = acs_reference.del.repository_id;
+
+        acs_object.del(repository_id);
+	person.del(v_maintainer_id);
+
+    end del;
+
+    function is_expired_p (
+	repository_id integer
+    ) return char
+    is
+	v_expiry_date date;
+    begin
+	select expiry_date into v_expiry_date
+	from   acs_reference_repositories
+	where  repository_id = is_expired_p.repository_id;
+
+	if nvl(v_expiry_date,sysdate+1) < sysdate then
+	    return 't';
+	else
+	    return 'f';
+	end if;
+    end;	    
+
+end acs_reference;
+/
+show errors

sql/postgresql/acs-reference-create.sql

+-- packages/acs-reference/sql/postgresql/acs-reference-create.sql
+--
+-- @author jon@jongriffin.com
+-- @creation-date 2001-07-16
+--
+-- @cvs-id $Id$
+
+-- setup the basic admin privileges
+
+select acs_privilege__create_privilege('acs_reference_create');
+select acs_privilege__create_privilege('acs_reference_write');
+select acs_privilege__create_privilege('acs_reference_read');
+select acs_privilege__create_privilege('acs_reference_delete');
+    
+select acs_privilege__add_child('create','acs_reference_create');
+select acs_privilege__add_child('write', 'acs_reference_write');
+select acs_privilege__add_child('read',  'acs_reference_read');
+select acs_privilege__add_child('delete','acs_reference_delete');
+
+-- Create the basic object type used to represent a reference database
+select acs_object_type__create_type (
+        'acs_reference_repository',
+        'ACS Reference Repository',
+        'ACS Reference Repositories', 
+        'acs_object',
+        'acs_reference_repositories',
+        'repository_id',
+        null,
+        'f',
+	null,
+	'acs_object__default_name'
+);
+
+-- A table to store metadata for each reference database
+-- add functions to do exports and imports to selected tables.
+
+create table acs_reference_repositories (
+    repository_id	integer
+			constraint arr_repository_id_fk references acs_objects (object_id)
+			constraint arr_repository_id_pk primary key,
+    -- what is the table name we are monitoring
+    table_name		varchar(100)  
+			constraint arr_table_name_nn not null
+			constraint arr_table_name_uq unique,
+    -- is this external or internal data
+    internal_data_p     boolean,
+    -- Does this source include pl/sql package?
+    package_name	varchar(100)
+			constraint arr_package_name_uq unique,
+    -- last updated
+    last_update		timestamptz,
+    -- where is this data from
+    source		varchar(1000),
+    source_url		varchar(255),
+    -- should default to today
+    effective_date	timestamptz, -- default sysdate
+    expiry_date		timestamptz,
+    -- a text field to hold the maintainer
+    maintainer_id	integer
+			constraint arr_maintainer_id_fk references persons(person_id),
+    -- this could be ancillary docs, pdf's etc
+    -- needs to be fixed for PG
+    -- DRB: needs to use Content Repository for both PG and Oracle, no???
+    lob 		integer
+);
+
+-- API
+
+
+-- default for Oracle
+
+create function acs_reference__new (integer,varchar,boolean,varchar,timestamptz,
+varchar,varchar,timestamptz,timestamptz,integer,integer,varchar,varchar,
+varchar,varchar,integer)
+returns integer as '
+declare
+    p_repository_id   alias for $1; -- default null
+    p_table_name      alias for $2; -- 
+    p_internal_data_p alias for $3; -- default "f"
+    p_package_name    alias for $4; -- default null
+    p_last_update     alias for $5; -- default sysdate
+    p_source          alias for $6; -- default null
+    p_source_url      alias for $7; -- default null
+    p_effective_date  alias for $8; -- default sysdate
+    p_expiry_date     alias for $9; -- default null
+    p_maintainer_id   alias for $10; -- default null
+    p_notes           alias for $11; -- default null (not Oracle empty_blob())
+-- I really see no need for these as parameters
+--    creation_date   alias for $12; -- default sysdate
+    p_first_names     alias for $12; -- default null
+    p_last_name      alias for $13; -- default null
+    p_creation_ip     alias for $14; -- default null
+    p_object_type     alias for $15; -- default "acs_reference_repository"
+    p_creation_user   alias for $16; -- default null
+    v_repository_id acs_reference_repositories.repository_id%TYPE;
+    v_object_type   acs_objects.object_type%TYPE;
+    v_maintainer_id persons.person_id%TYPE;
+begin
+    if p_object_type is null then
+        v_object_type := ''acs_reference_repository'';
+    else
+        v_object_type := p_object_type;
+    end if;
+
+    v_repository_id := acs_object__new (
+         p_repository_id,    
+         v_object_type,
+         now(),
+         p_creation_user,
+         p_creation_ip,
+         null
+    );
+
+    -- This logic is not correct as the maintainer could already exist
+    -- The way around this is a little clunky as you can search persons
+    -- then pick an existing person or add a new one, to many screens!
+    -- I really doubt the need for person anyway.
+    --
+    -- It probably needs to just be a UI function and pass
+    -- in the value for maintainer.
+    --
+    -- IN OTHER WORDS
+    -- Guaranteed to probably break in the future if you depend on
+    -- first_names and last_name to still exist as a param
+    -- This needs to be updated in the Oracle version also
+    -- NEEDS TO BE FIXED - jag
+
+    if p_first_names is not null and p_last_name is not null and p_maintainer_id is null then
+        v_maintainer_id := person__new (null, ''person'', now(), null, null, null, null,
+	                                p_first_names, p_last_name, null);
+	else if p_maintainer_id is not null then
+           v_maintainer_id := p_maintainer_id;
+        else 
+	    v_maintainer_id := null;
+	end if;
+    end if;
+
+    insert into acs_reference_repositories
+        (repository_id,table_name,internal_data_p,
+         last_update,package_name,source, 
+         source_url,effective_date,expiry_date,
+         maintainer_id,lob)
+    values 
+        (v_repository_id, p_table_name, p_internal_data_p,
+         p_last_update, p_package_name, p_source, p_source_url,
+         p_effective_date, p_expiry_date, v_maintainer_id, p_notes);
+
+    return v_repository_id;    
+end;
+' language 'plpgsql';
+
+-- made initially for PG 
+create function acs_reference__new (varchar,timestamptz,
+varchar,varchar,timestamptz)
+returns integer as '
+declare
+    p_table_name      alias for $1; -- 
+    p_last_update     alias for $2; -- default sysdate
+    p_source          alias for $3; -- default null
+    p_source_url      alias for $4; -- default null
+    p_effective_date  alias for $5; -- default sysdate
+    v_repository_id acs_reference_repositories.repository_id%TYPE;
+begin
+    return acs_reference__new(null, p_table_name, ''f'', null, null, p_source, p_source_url,
+                              p_effective_date, null, null, null, null, null, null,
+                              ''acs_reference_repository'', null);
+end;
+' language 'plpgsql';
+
+
+create function acs_reference__delete (integer)
+returns integer as '
+declare
+    p_repository_id alias for $1;
+    v_maintainer_id		acs_objects.object_id%TYPE;
+begin
+    select maintainer_id into v_maintainer_id
+    from   acs_reference_repositories
+    where  repository_id = p_repository_id;
+
+    delete from acs_reference_repositories
+    where repository_id = p_repository_id;
+
+    perform acs_object__delete(p_repository_id);
+    return 0;
+end;
+' language 'plpgsql';
+
+create function acs_reference__is_expired_p (integer)
+returns char as '
+declare
+    repository_id alias for $1;
+begin
+    select expiry_date into v_expiry_date
+    from   acs_reference_repositories
+    where  repository_id = is_expired_p.repository_id;
+
+    if coalesce(v_expiry_date,now()+1) < now() then
+        return ''t'';
+    else
+        return ''f'';
+    end if;
+end;
+' language 'plpgsql';
+

sql/postgresql/acs-reference-drop.sql

+-- packages/acs-reference/sql/postgresql/acs-reference-data.sql
+--
+-- Drop the ACS Reference packages
+--
+-- @author jon@jongriffin.com
+-- @dropd 2001-07-16
+--
+-- @cvs-id $Id$
+--
+
+-- drop all associated tables and functions
+
+-- DRB: in PG we could do this dynamically as JonG has done in Oracle.  The
+-- proc name can easily be picked up from pg_proc since we use unique package
+-- keys as prefaces.   The params can be picked up as well but I don't know
+-- how off the top of my head.  It would be a nice to write a general function
+-- to do this in both Oracle and PG - "drop_package_functions(package_key)".
+
+    
+select acs_privilege__remove_child('create','acs_reference_create');
+select acs_privilege__remove_child('write', 'acs_reference_write');
+select acs_privilege__remove_child('read',  'acs_reference_read');
+select acs_privilege__remove_child('delete','acs_reference_delete');
+
+select acs_privilege__drop_privilege('acs_reference_create');
+select acs_privilege__drop_privilege('acs_reference_write');
+select acs_privilege__drop_privilege('acs_reference_read');
+select acs_privilege__drop_privilege('acs_reference_delete');
+
+select acs_object__delete(repository_id)
+from acs_reference_repositories;
+
+select acs_object_type__drop_type ('acs_reference_repository', 't');
+
+drop function acs_reference__new (varchar,timestamptz, varchar,varchar,timestamptz);
+drop function acs_reference__new (integer,varchar,boolean,varchar,timestamptz,
+varchar,varchar,timestamptz,timestamptz,integer,integer,varchar,varchar,
+integer,varchar,integer);
+drop function acs_reference__delete (integer);
+drop function acs_reference__is_expired_p (integer);
+drop table   acs_reference_repositories;
+

tcl/acs-reference-procs.tcl

+ad_library {
+    Utility procs for working with data in acs-reference
+
+    @author Jon Griffin <jon@jongriffin.com>
+    @creation-date 2001-08-28
+    @cvs-id $Id$
+}
+
+ad_proc -private acs_reference_get_db_structure {
+	{-table_name:required}
+} {
+    Query the DB to get the data structure.  Utility function.
+} {
+
+}

www/doc/design.html

+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<html>
+<head><title>acs-reference Design Documentation</title></head>
+<body bgcolor=white text=#000000>
+<h2>acs-reference Design Documentation</h2>
+<h3>I.  Essentials</h3>
+<ul>
+<li>There is no user accessible directory</li>
+<li>There is no sub-site admin accessible diretory</li>
+<p>
+<li>Requirements document:  <a  href="requirements.html">Requirements</a>
+<li>Data model:?? where does this really go? </a>
+<li>ER diagram: None yet 
+</ul>
+
+<h3>II.  Introduction</h3>
+Reference data is often overlooked in the rush to get coding. In reality, much of ....
+<h3>III.  Historical Considerations</h3> 
+Before the existence of acs-reference, the ACS required that you preload some tables in a script to get some basic reference functionality. There were many problems with this:
+<ul>
+<li>No easy way to find out what reference data even existed.</li>
+<li>No way to find out how old the data was.</li>
+<li>No way to find out where that data came from.</li>
+<li>Very US/English slant on the data.</li>
+</ul>
+<h3>  IV. Competitive Analysis</h3>
+The only real competition is internally developed solutions. 
+<h3>  V. Design Tradeoffs</h3>
+<h4>Primary Goals</h4>
+<ul>
+<li>This system was designed with maintainability and reusability as its primary goals. By wrapping a layer around all of the reference tables we have increased the maintainability immensely.</li>
+<li>Another goal was to bring together many different types of data and present them in a logical fashion. It was amazing how little of this data is available on the internet in a database friendly form.</li>
+</ul>
+<h4>Performance</h4>
+When updating the reference tables their is overhead due to the fact that the table is registered with the repository. This should rarely occur anyway as the tables are only added once. 
+By not having the actual data itself in the acs-object system, subsequent additions and deletions to the reference tables themselves are unaffected by this overhead.
+<h3>  VI. API</h3>
+<h3>  VII. Data Model Discussion</h3>
+<h3>  VIII. User Interface</h3>
+Their is no end user interface.
+There will 
+<h3>  IX. Configuration/Parameters</h3>
+None
+<h3>  X. Future Improvements/Areas of Likely Change</h3>
+A server based update mechanism will be supported. This will allow for tables to be updated (and preferably diffed) instead of being reloaded with a package upgrade.
+An interface to produce xml/csv from the reference data would be a nice service to the community (allowing legacy applications a way to import this data).
+<h3>  XI. Authors</h3>
+<h3>  XII. Revision History</h3>
+<pre>
+$Log$
+Revision 1.1  2001/04/22 00:53:12  jong
+initial openacs import
+
+Revision 1.2  2000/12/13 04:39:00  jong
+Added Revision History and corrected typo in reference link
+
+</pre>
+</body>
+</html>

www/doc/index.html

+<!-- $Id$ -->
+
+<html>
+<head><title>ACS Reference Documentation</title></head>
+<body bgcolor=#ffffff>
+<h2>ACS Reference Documentation</h2>
+<hr>
+<h3>Engineering Docs</h3>
+<ul>
+<li><a href="requirements.html">Requirements</a>
+<li><a href="design.html">Design</a>
+</ul>
+Current docs are always at:<br>
+<a href="http://www.jongriffin.com/static/openacs">jongriffin.com</a>
+<h3>Release Notes</h3>
+
+<p>Please file bugs in the <a href="http://www.openacs.org/sdm/">SDM</a>.</p>
+
+<hr>
+<address><a href="mailto:jon@jongriffin.com">jon@jongriffin.com</a></address></body>
+</html>
+
+
+

www/doc/requirements.html

+<!-- $Id$ -->
+<head>
+<title>ACS Reference Requirements</title>
+</head>
+<body bgcolor=#ffffff>
+<h2>ACS Reference Requirements</h2>
+by <a href="mailto:jon@jongriffin.com">Jon Griffin</a>
+<hr>
+<h3>I. Introduction</h3>
+This document describes the requirements for the ACS Reference service
+package. This package has the following primary functions:
+<ul>
+<li>It allows applications to refer to and employ a common set of reference
+data.</li>
+<li>It gives administrators the ability to run standard reports on this data.</li>
+<li>It offers a convenient repository for and the ability to run reports on
+data of this sort.</li>
+<li>It allows us to monitor the usage of reference data.</li>
+</ul>
+<h3>II. Vision Statement</h3>
+<p>What is reference data? Simply put, it is data that doesn't change
+very often and also in many cases comes from an external source and not
+from within the system itself.  Many times it is created from a standards
+body, i.e. <a href="http://www.iso.ch/">ISO</a> or <a href="http://www.ansi.org">ANSI</a>, and may be required for a client's particular industrial needs.
+<p>Some examples of reference data are:
+<ul>
+<li>Geographic data: zip codes, country codes and states/provinces</li>
+<li>Standards bodies data: ISO 4217 currency codes, ISO 3166 Country Codes, ITU
+Vehicle Signs</li>
+<li>Quasi-Standards: S&amp;P Long-term Issuer Credit Ratings</li>
+<li>Internal: Status Codes, Employee Position Codes</li>
+</ul>
+Historically, reference data has been looked upon by developers as
+something less important than more immediate coding needs, and so most
+data models simply defer the issue by treating reference data as
+something simple to implement. Elsewhere. The reality is
+that for most organizations reference data is extremely important and
+also extremely difficult to manage.
+<p>This module will not only <i>package</i> all of a site's reference
+data in one place, it will also help manage that data.
+<h3>III. System Overview</h3>
+The ACS Reference package consists of:
+<ul>
+<li>A standard framework for monjitoring and modifying reference data.
+<li>A method of determining whether or not that data is expired.
+<li>The ability to include not only the data but also functions to
+work with that data.
+</ul>
+<h3>IV. Use-cases and User-Scenarios</h3>
+Papi Programmer is developing a module that will use country codes as
+part of his table structure. Instead of creating his own table he can
+use the ACS Reference package and the country codes therein. If the
+country codes change - which does in fact happen from time to time -
+the ACS Reference package will maintain that information for him.
+<h3>V. Related Links</h3>
+<ul>
+<li> <a href=design.html>Design document</a>
+</ul>
+
+<h3>VI.A Requirements: Data Model</h3>
+
+10.10 The package should use a table that is the <i>master</i> table for all reference tables.
+<br>10.20 The package should employ a field to show whether this data is internally derived or not.
+<br>10.30 The package should employ a field to signify whether there is a PL/SQL package involved with
+this table.
+<br>10.40 The package should offer an indicatation of when this data was last updated.
+<br>10.50 The package should offer an indication of what the original source of this data was.
+<br>10.60 The package should offer an indication of what the original source URL was, if any.
+<br>10.70 The package should offer a representation of effective datetime
+<br>10.80 The package should offer a representation of discontinued datetime
+<br>10.90 The package should keep an indication of who the data maintainer is, by user_id.
+
+<h3>VI.B Requirements: API</h3>
+
+20.10 The package should offer a function to determine if a particular table has expired.<p>
+
+The requirements below are not met by the current implementation:<p>
+
+30.10 There needs to be a way to query the data source and update
+automatically.  If that isn't possible, as it won't be in many cases,
+the application should be able to query a master server and see if
+there is new data for a particular table or tables.  For example:
+refdata.arsdigita.com could hold the reference tables and when newer
+table versions become available, simply upload only these versions or
+perhaps even only the differences between the tables.
+
+<h3>VII. Implementation Notes</h3>
+The package needs to handle changes to reference data in a graceful
+fashion. For example, if a country splits into two or more countries, what should happen? 
+<ul>
+<li>The reference package should note this change.</li>
+<li>The appropriate table is updated. In this case countries et al.</li>
+<li>An update to the repository database field effective_date is added.</li>
+<li>A <i>diff</i> type of entry into the reference repository history. <font color = "red"><i>This is not in the current data model</i></font>
+<li>Then any sub-programs using this data will note the change of effective date and be able to handle the change as needed (i.e. simply read the new table).</li>
+<li>Historical data will be available using this <i>diff</i> for those applications that need to use the old data</li>
+</ul>
+Note also that it is possible to have overlapping effective dates. 
+This will not be implemented in the first version, but should be recognized and accomodated throughout the development
+process for the service package.  
+
+<h3> VIII. Revision History</h3>
+
+<pre>
+$Log$
+Revision 1.1  2001/04/22 00:53:12  jong
+initial openacs import
+
+Revision 1.7  2000/12/15 04:09:25  jfinkler
+fixed numbering scheme
+
+Revision 1.6  2000/12/13 04:33:47  jong
+Updated doc for alpha release
+
+Revision 1.5  2000/12/12 06:29:21  jfinkler
+spelling error, my fault
+
+Revision 1.4  2000/12/12 06:28:05  jfinkler
+fixed a few formatting errors
+
+Revision 1.3  2000/12/12 06:26:20  jfinkler
+reorganized content, edited for clarity
+
+Revision 1.2  2000/12/08 02:41:31  ron
+initial version
+
+</pre>
+
+</body>
+</html>
+
+</body></html>

www/index.adp

+<master>
+<property name="context">@context_bar;noquote@</property>
+<property name="title">@title;noquote@</property>
+<h2>@title@;noquote</h2>
+
+<ul>
+ <li><a href="reference-data-list">List Reference Data</a></li>
+</ul>
+<hr>
+<h3>Reports</h3>
+Coming soon!
+<if @admin_p@ ne 0 >
+<hr>
+<h3>Admin</h3>
+  None Yet
+  <!--a href="admin/reference-list">Maintenance</a -->
+</if>
\ No newline at end of file

www/index.tcl

+ad_page_contract {
+
+    Main Index page for reference data. 
+
+    @author Jon Griffin (jon@jongriffin.com)
+    @creation-date 2001-08-26
+    @cvs-id $Id$
+} {
+} -properties {
+  context_bar:onevalue
+  package_id:onevalue
+  user_id:onevalue
+  title:onevalue
+}
+
+set title "Reference Data"
+set package_id [ad_conn package_id]
+set context_bar [list $title]
+set user_id [ad_verify_and_get_user_id]
+
+set admin_p [ad_permission_p $package_id admin]
+
+ad_return_template

www/reference-data-list-oracle.xql

+<?xml version="1.0"?>
+
+<queryset>
+   <rdbms><type>oracle</type><version>8.1.6</version></rdbms>
+
+<fullquery name="data_select">      
+      <querytext>
+       
+select repository_id,
+  table_name,
+  internal_data_p,
+  package_name,
+  to_char(last_update,'MM-DD-YYYY') updated,
+  source,
+  source_url,
+  effective_date,
+  expiry_date
+from  acs_reference_repositories a
+order by table_name
+
+      </querytext>
+</fullquery>
+
+ 
+</queryset>

www/reference-data-list-postgresql.xql

+<?xml version="1.0"?>
+
+<queryset>
+   <rdbms><type>postgresql</type><version>7.1</version></rdbms>
+
+<fullquery name="data_select">      
+      <querytext>
+       
+select repository_id,
+  table_name,
+  internal_data_p,
+  package_name,
+  to_char(last_update,'MM-DD-YYYY') as updated,
+  source,
+  source_url,
+  effective_date,
+  expiry_date
+from  acs_reference_repositories a
+order by table_name
+
+      </querytext>
+</fullquery>
+
+ 
+</queryset>

www/reference-data-list.adp

+<master>
+<property name="context">@context_bar;noquote@</property>
+<property name="title">@title;noquote@</property>
+
+<if @data:rowcount@ eq 0>
+<i>You have no reference data in the database right now.</i><p>
+</if>
+
+<else>
+    <ul>
+    <multiple name=data>
+    <li><a href="view-one-reference?repository_id=@data.repository_id@">@data.table_name@</a></li>
+    </multiple>
+    </ul>
+</else>    
+
+
+
+
+

www/reference-data-list.tcl

+ad_page_contract {
+    This page lists all the formats
+    
+    @author Jon Griffin (jon@jongriffin.com)
+    @creation-date 2000-10-04
+    @cvs-id $Id$
+} {
+} -properties {
+    context_bar:onevalue
+    package_id:onevalue
+    user_id:onevalue
+    data:multirow
+}
+
+
+set package_id [ad_conn package_id]
+set title "List Reference Data"
+set context_bar [list "$title"]
+ 
+set user_id [ad_verify_and_get_user_id]
+
+db_multirow data data_select { 
+}
+
+ad_return_template
\ No newline at end of file

www/table-detail.adp

+<master>
+<property name="context">@context_bar;noquote@</property>
+<property name="title">@title;noquote@</property>

www/table-detail.tcl

+ad_page_contract {
+    This page views the table structure
+    
+    @param table_name 
+    @author Jon Griffin (jon@jongriffin.com)
+    @creation-date 17 Sept 2001
+    @cvs-id $Id$
+} {
+    table_name:notnull
+} -properties {
+    context_bar:onevalue
+    package_id:onevalue
+    user_id:onevalue
+    table_info:onerow
+}
+
+set package_id [ad_conn package_id]
+set title "View one Table Structure"
+set context_bar [list "$title"]
+set user_id [ad_verify_and_get_user_id]
+
+
+ad_return_template
\ No newline at end of file

www/view-one-reference.adp

+<master>
+<property name="context_bar">@context_bar;noquote@</property>
+<property name="title">@title;noquote@</property>
+
+<table>
+<tr><th valign=top align=right>Table Name</th>
+<td> <a href="table-detail?table_name=@table_info.table_name@">@table_info.table_name@</a> </td></tr>
+
+<tr><th valign=top align=right>Package Name</th>
+<td> @table_info.package_name@ </td></tr>
+
+<tr><th valign=top align=right>Internal Data?</th>
+<td> @table_info.internal_data_p@ </td></tr>
+
+<tr><th valign=top align=right>Source</th>
+<td> @table_info.source@ </td></tr>
+
+<tr><th valign=top align=right>Source URL</th>
+<td> @table_info.source_url@ </td></tr>
+
+<tr><th valign=top align=right>Last Update</th>
+<td> @table_info.last_update@ </td></tr>
+
+<tr><th valign=top align=right>Effective Date</th>
+<td> @table_info.effective_date@ </td></tr>
+
+<tr><th valign=top align=right>Expiry Date</th>
+<td> @table_info.expiry_date@ </td></tr>
+
+<tr><th valign=top align=right>Maintainer</th>
+<td> @table_info.maintainer_id@ </td></tr>
+
+</table>
+
+
+

www/view-one-reference.tcl

+ad_page_contract {
+    This page views one table of reference data
+    
+    @param repository_id 
+    @author Jon Griffin (jon@jongriffin.com)
+    @creation-date 17 Sept 2001
+    @cvs-id $Id$
+} {
+    repository_id:integer,notnull
+} -properties {
+    context_bar:onevalue
+    package_id:onevalue
+    user_id:onevalue
+    table_info:onerow
+}
+
+set package_id [ad_conn package_id]
+set title "View one Table"
+set context_bar [list [list "reference-list" "Reference List" ] "$title"]
+set user_id [ad_verify_and_get_user_id]
+
+db_1row get_table { *SQL* } -column_array table_info
+
+ad_return_template

www/view-one-reference.xql

+<?xml version="1.0"?>
+
+<queryset>
+<fullquery name="get_table">
+ <querytext>
+    select repository_id,
+    table_name,
+    internal_data_p,
+    package_name,
+    last_update,
+    source,
+    source_url,
+    effective_date,
+    expiry_date,
+    (select user_id
+     from cc_users u
+     where user_id = maintainer_id) as maintainer_id
+    from acs_reference_repositories r
+    where repository_id= :repository_id
+</querytext>
+</fullquery>
+</queryset>
\ No newline at end of file