source: ndgCommon/trunk/README.txt @ 5197

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

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