This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Annotation of /lib/A3C.pod

Parent Directory Parent Directory | Revision Log Revision Log

Revision 210 - (hide annotations)
Fri Jun 20 12:27:13 2008 UTC (11 years, 11 months ago) by dpavlin
File size: 6224 byte(s)
tweaks, spellcheck
1 dpavlin 204 =head1 NAME
3     A3C = AAAC; AAA from "Authentication, Authorization and Accounting" and C from "CARNet".
5     =head1 DESCRIPTION
7 dpavlin 205 This page describes general idea about A3C application and current status of implementation.
8 dpavlin 204
9 dpavlin 210 Opinions should be attributed to Dobrica Pavlinusic, and not other developers :-)
10     It's supposed to convey a story which is coherent enough for new developer
11 dpavlin 205 to join into project. Most of other documentation is more useful when
12     developing and looking into code usage (if it's not documented and tested,
13     it doesn't exist) but this part is delivered as pure POD for reading pleasure.
15 dpavlin 207 =head1 Models
17     Models in Jifty are at perl level objects (with validation and
18     canonicalization) and tables in database.
20     For a start, we implement some magic documented in L<A3C::Record> on records
21     (rows in database).
23     Then, we need to mungle data without re-thinking SQL queries which would
24     produce same results, so there is L<A3C::SQL> which produce objects that
25     look like L<Jifty::Collection>s, but aren't. This allows us to switch into
26     SQL in views if needed.
28     This method is not perfect, and shouldn't be used instead of Jifty models
29     just to write SQL because it doesn't do any permission checking. However,
30 dpavlin 210 it's a huge help for complex C<GROUP BY> and C<JOIN> queries which are hard
31 dpavlin 207 to express using L<Jifty::DBI>.
33     If we needed to generate those queries from within program (from user data,
34     for example) something like L<Fey::SQL> would be much better tool.
36 dpavlin 204 =head1 LDAP
38 dpavlin 210 Implement LDAP entry and edit interface (interesting problem since most
39 dpavlin 208 entries can have multiple values which doesn't map nicely to relational
40     schema).
41 dpavlin 204
42 dpavlin 210 This task can be broken down into following parts:
44 dpavlin 208 =head2 Multiple values
46 dpavlin 210 When creating records with ARRAY values L<A3C::Record/create>
47 dpavlin 208 joins values with magic marker between them to make rest of Jifty happy.
49     Plan is to use full-text search engine to search over data anyway, so this
50     is not serious limitation. If needed, something like bitmap indexes could be
51 dpavlin 210 used at database level to expose those values for filtering. For joins we
52 dpavlin 208 would probably need separate materialized many-many tables which could be
53     created more-or-less automatically in L<A3C::Record>.
55 dpavlin 204 =head2 Import data from existing LDAP server
57 dpavlin 210 C<bin/import-ldap.pl> has embedded documentation and uses L<A3C::LDAP>
58 dpavlin 204
59 dpavlin 208 L<http://a3c.skole.hr/ldap/> is user interface to L<A3C::View::LDAP> and
60     L<A3C::Action::SyncOrganization>
62 dpavlin 204 =head2 Query existing LDAP server
64     Since we are creating local copy of data, we need easy way to ask master
65     LDAP server for data. L<A3C::LDAP> provides way to query LDAP and receive
66     something similar enough to L<Jifty::Collection> so that L<A3C::View>s
67     doesn't have to be edited to switch from Jifty models to LDAP
68     data.
70     =head2 Create new entries and edit existing ones
72 dpavlin 210 We are in the middle of migration from (generic) L<A3C::Model::Person> and
73 dpavlin 204 L<A3C::Model::Organization> to our custom L<A3C::Model::hrEduOrg> and
74     L<A3C::Model::hrEduPerson>
76 dpavlin 210 Most views I guess, will be implemented by sub-classing L<Jifty::View::Declare::CRUD>.
77 dpavlin 204 Right now L<A3C::View::Organization> is such implementation.
79     Planned C<A3C::View::hrEduPerson> will implement another such view, and I
80     hope to see some kind of code reuse there (which should probably move to
81 dpavlin 210 C<Jifty::Plugin::TableCRUD>).
82 dpavlin 204
83     =head2 Virtual LDAP server to publish data
85     This part is in planning stage, and it will probably be based on L<Net::LDAP::Server>.
87     =head1 Existing LDAP schema
89     First, we needed a clever way to import existing LDAP schema into Jifty. So,
90     C<bin/ldap2model.pl> helper was created to handle that.
92     Some entries in LDAP schema have fixed list of attributed, and L<A3C::AAIEduHr>
93     implements fetcher (with cache) for that data.
95     =head1 Legacy portal integration
97     =head2 Parse PHP config files
99     Configuration files in PHP is only place in which part of portal
100     configuration is specified. To handle it in A3C, we use
101 dpavlin 210 L<A3C::Model::StrixInstance> which aggregates all instance data. Parser is
102 dpavlin 204 implemented by L<A3C::PHP>
104     =head2 Connect to remote database
106     Implemented in two different ways:
108     =head3 Direct SQL execution
110     L<A3C::Action::StrixSQL> and interface as L<A3C::View::Strix/sql>.
112     =head3 Fetching data hashes
114     C<Strix> (which doesn't link well from on-line documentation so you will
115     have to take a look in C<lib/Strix.pm>) implements pure DBI code (ported
116     from php) to access data directly. Keep in mind that this data have to be
117 dpavlin 210 cached for any reasonable performance. On the other hand, data can be
118 dpavlin 205 structured usefully, for example trees are structured in useful way for
119     direct output to JSON.
120 dpavlin 204
121     If tree has C<class> key, it can be set to C<error> so that we can mark
122     errors in data using same CSS class in views. This might be useful convention.
124 dpavlin 205 I prefer to keep this file documented up to level that make it's usage from Jifty and
125 dpavlin 210 C<t/50-strix.t> makes sense, but not more than that.
126 dpavlin 205
127 dpavlin 204 =head1 HTML
129     We don't generate HTML using templates. In fact, all HTML is encoded in perl
130     code using L<Template::Declare>. This allows easy generation of valid HTML,
131     high-level templates which are perl code and easy skinning using CSS.
133     C<share/web/static/css/app.css> is used to store application specific CSS.
134     It should probably be split into several files (Jifty will concatenate them
135     for us anyway) for easier maintenance, probably by same logic as view names
136     to skip additional step of mapping when human are watching into code.
138 dpavlin 205 In long run, this should allow us to refactor templates at code level and
139     create different re-usable widgets which brings us to following topic...
141     =head1 AJAX
143     Jifty's way of AJAX are L<Jifty::Manual::PageRegions>.
145     =head2 Strix navigation
147     L<http://a3c.skole.hr/strix/navigation>
149     For now, we have implementation of two-level select which is in sync with
150     instance clipboard (implemented by L<A3C::Model::StrixInstanceSelection> and
151     L<A3C::View::Strix> and L<A3C::Action::StrixSelectSite>. This is
152     good candidate to refactor into reusable widget on it's own.
154 dpavlin 204 =head1 BUGS
156     Many probably, documented in C<TODO> which is also useful for quick overview
157 dpavlin 210 what changed between versions if svn commit log is too detailed although
158 dpavlin 204 first line of commit message might be good summary of each individual
159     change.

  ViewVC Help
Powered by ViewVC 1.1.26