source: ndgCommon/trunk/README.txt @ 5011

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/ndgCommon/trunk/README.txt@5192
Revision 5011, 4.9 KB checked in by cbyrom, 11 years ago (diff)

Add main README.txt documentation to codebase giving an overview of
the complete codebase along with descriptions of the structure and
info on important details. Also extend the setting up eXist and the test documentation.

Line 
1ndgCommon codebase overview
2-------------------------------
3ndgCommon is a codebase to hold code that may be useful across different projects
4- to avoid duplication of effort and to provide well maintained, reliable
5tools to improve development efficiency.  It is based on the earlier ndgUtils - with
6as mcuh
7
8The bulk of the codebase consists of a series of clients - to XML DBs, postgres and
9webservices - as well as simple http clients.  Where functionality is likely to be
10shared (e.g. the webservice and eXist search clients both offer the same functions -
11but to different data sources), coding is done against interface classes - to
12improve decoupling of concerns and improve future extensibility.
13
14Additionally, a series of utility and data model classes are provided to help with common
15tasks - e.g. fileutilities has methods to cope with normal IO file access.
16
17Lastly, a significant test suite is provided to sanity check any changes made
18to the codebase.
19
20
21Codebase Structure
22------------------
23/ - top level dir has setup scripts, eclipse project files and this README.txt
24
25/ndg/common - base stem to provide meaningful package naming to codebase
26
27/ndg/common/src/tools - contains any command line tools that may be useful anywhere
28- currently contains tools to validate atom doc contents in eXist
29
30/ndg/common/src/models - contains data models representing data objects used
31elsewhere in the ndg codebase.  A lot of these models support the old moles 1.3
32format - so if this is removed from support, this package can be tidied up
33substantially
34
35/ndg/common/src/lib - common code libraries which either are utility classes or
36don't fit comfortably in other packages.  Of particular note is ndgresources
37which replaces ndgXqueries and which allows access to non code based resources
38packaged with the codebase - e.g. xqueries and xml schemas - see section below on
39accessing non code resources
40
41/ndg/common/src/dal - data access layer code.  This typically contextualises
42client usage - e.g. so that the appropriate data access client is used for the
43environment in which it is running.  I'm not sure ndgDirectory is actually used
44but have retained it just in case.
45
46/ndg/common/src/clients - top level package for clients.  Different clients available
47in subpackages as follows:
48
49../http/ - simple http clients for retrieving URLs, searching via RESTful interfaces
50and looking up vocab term data
51
52../reldb/ - clients for interacting with relational databases.  Currently only
53includes a postgres client
54
55../ws/ - web service clients.  Currently only includes a client for the discovery
56web service
57
58../xmldb/ - clients to XML DBs.  Currently only includes eXist based clients
59
60../xmldb/eXist - clients for communicating direct with eXist APIs (xmlrpcclient, restclient)
61as well as higher level clients for doing more involved things (searchclient, crudclient) and
62to support the atom format for moles (atomclient) and associated feeds (feedclient).
63
64/ndg/common/unittests - package with structure mirroring the src package with
65unittests to exercise the various src classes.  See section on testing, below, for
66more info.
67
68/ndg/common/xmldb - various non code files used by the XML DB and XML DB clients.  NB, these
69are accessible in code via the ndgresource module - see below.
70
71/ndg/common/xmldb/indexing - index configuration files to improve indexing of
72XML DBs
73
74/ndg/common/xmldb/resources - misc XML docs - currently contains DIF snippets
75required when producing DIF records from atom moles docs
76
77/ndg/common/xmldb/schema - schema referenced by XML docs in the XML DB
78
79/ndg/common/xmldb/setup - instructions for setting up the XML DB for use with ndgCommon
80/ndg/common/xmldb/xquery - and xquery and xquery libs used by the XML DB
81
82
83Non-code ndgCommon resources
84-----------------------
85Replacing the ndgXqueries module of ndgUtils, ndgCommon provides a module, ndgresources
86with a class, NDGResources to access any non code document stored in ndgCommon (e.g.
87xqueries, XML schemas, etc).
88
89To access any of these resources, instantiate a NDGResource object and the use the
90appropriate dictionary exposed by the object (xq, xqlib, resource, xsd, indexes) to get
91at the docs.  Alternatively, if an xquery is required, us the createXQuery method to
92generate the query directly.
93
94NB, if new resources need to be added, ensure, if new directories are to be added,
95that these are included in the setup.py package_data variable.
96
97
98XML DB Config
99------------------
100The ndgCommon codebase is designed to allow different clients to be provided
101for different XML databases.  At present, however, only the eXist DB is
102supported.  Instructions on how to configure this for use with ndgCommon are
103found at:
104
105ndgcommon/ndg/common/xmldb/setup/eXist/ReadMe.txt
106
107
108Tests
109------------------
110Instructions for running the test suite can be found at:
111
112ndgcommon/ndg/common/unittests/README.txt
113
Note: See TracBrowser for help on using the repository browser.