Project

General

Profile

Revision 881

Added by berkley almost 19 years ago

updated documentation. removed a lot of typos and updated all of the new stuff for the new release

View differences:

docs/user/packages.html
28 28
  </table>
29 29
  <p>Metacat allows a user to create a virtual link between XML documents within
30 30
  the system.  These links are called <i>Relationships</i> and are defined by triples
31
  in <i>eml-dataset-2.0</i> files.  A relationship can be defined between two
31
  in <i>eml-dataset</i>, <i>eml-literature</i> or <i>eml-software</i> files.  A relationship can be defined between two
32 32
  XML or <a href="./datafiles.html">non-XML</a> files. 
33 33
  The following is an example of an eml-dataset-2.0 file holding triples at the end:</p>
34 34
  
......
117 117
  DTD (-//NCEAS//eml-dataset-2.0//EN).  The package doctype is an application 
118 118
  property of Metacat.  Setting this property (and others) is described in 
119 119
  <a href="./properties.html">Setting Metacat Properties</a>.  The package file
120
  is broken up into <i>n</i> triples.  Each triple has a subject, relationship,
120
  contains <i>n</i> triples.  Each triple has a subject, relationship,
121 121
  and an object.  This grouping can be read as follows:  &lt;subject&gt; has
122 122
  &lt;relationship&gt; to &lt;object&gt;.  Each triple is a logical link
123 123
  between the subject and object with the relationship being a description of that
docs/user/acontrol.html
29 29
  </table>
30 30
  <p><b>Authentication</b></p>
31 31
    <p>Metacat has a public interface for porting authentication 
32
      schemes to Metacat.  Currently LDAP scheme is implemented. 
32
      schemes to Metacat.  Currently an LDAP scheme is implemented. 
33 33
      LDAP stands for Lightweight Directory Access Protocol. 
34
      It is optimized database for fast retrival of stored data:
34
      It is an optimized database for fast retrival of stored data:
35 35
      It is used by Metacat to store its users and their information. 
36 36
      The users can be organized in one or more groups.
37 37
    </p>
38 38
    <P> <img src="auth.gif"> 
39 39
    <P> <b>Access control in Metacat. </b></p>
40 40
    <ul>
41
      <li> Metacat users stored in the LDAP directory database are authenticated to use Metacat services and resources.</li>
41
      <li> Metacat users stored in the LDAP directory database are authenticated
42
      to use Metacat services and resources.</li>
42 43
      <li> A persistant session is assigned to an authenticated user.</li>
43
      <li> Metacat also allows document level access control via Access Control Lists (ACLs).</li>
44
      <li> Metacat also allows document level access control via Access Control 
45
      Lists (ACLs).</li>
44 46
    </ul>
45 47
  <!--<img src="acontrol.gif">-->
46 48
  <b>ACLs</b>
47
  <p>Metacat allows a user to set permissions for users or groups on individual documents by using
48
  a special XML file called an Access file.  The <a href="./packages.html">Package</a> file
49
  <p>Metacat allows a user to set permissions for users or groups on individual 
50
  documents by using
51
  a special XML file called an Access file.  
52
  The <a href="./packages.html">Package</a> file
49 53
  specifies which documents the Access file refers to. 
50
  These are the same documents the permissions are assigned for.
51 54
  A sample Access file looks like the following:</p>
52 55
  <pre>
53 56
    &lt;?xml version="1.0"?&gt;
......
102 105
     itself as stored in Metacat.
103 106
  </p>
104 107
  <p>Next are the permissions themselves.  An allow tag gives permissions to 
105
  the specified user(s) (&lt;principal&gt;) and a deny tag take the permissions
108
  the specified user(s) (&lt;principal&gt;) and a deny tag takes the permissions
106 109
  away from the user(s).  A principal should be a registered user or group.
107 110
  A timed duration can be set on the permission after
108 111
  which the user(s) will no longer have the specified permission.  A ticket count
......
113 116
    
114 117
  <br>
115 118
  <a href="./xmlindex.html">Back</a> | <a href="./metacattour.html">Home</a> | 
116
  <a href="./metacatout.html">Next</a>
119
  <a href="./ldap.html">Next</a>
117 120
</BODY>
118 121
</HTML>
119 122

  
docs/user/properties.html
80 80
      <td>10</td>
81 81
    </tr>
82 82
    <tr>
83
      <td>resultStyleURL</td>
84
      <td>The URL to the default stylesheet that Metacat should use to 
85
      transform XML documents when qformat is set to HTML. <br>
86
      DEPRECATED</td>
87
      <td>file:///opt/tomcat/webapps/knb/style/resultset.xsl</td>
83
      <td>config-dir</td>
84
      <td>directory where the style-sets exist</td>
85
      <td>/opt/tomcat/webapps/metacat/lib</td>
88 86
    </tr>
89 87
    <tr>
88
      <td>default-style</td>
89
      <td>the style-set to use if qformat is set to 'html'</td>
90
      <td></td>
91
    </tr>
92
    <tr>
90 93
      <td>xmlcatalogfile</td>
91 94
      <td>The default file type catalog file location.<br>
92 95
      DEPRECATED</td>
93 96
      <td>/opt/tomcat/webapps/xmltodb/catalog.txt</td>
94 97
    </tr>
95 98
    <tr>
96
      <td>defaultdatapath</td>
97
      <td>DEPRECATED</td>
98
      <td>C:\Temp\</td>
99
      <td>siteCode</td>
100
      <td>The code for the current site.</td>
101
      <td>NCEAS</td>
99 102
    </tr>
100 103
    <tr>
101
      <td>executescript</td>
102
      <td>DEPRECATED</td>
103
      <td>test.bat</td>
104
    </tr>
105
    <tr>
106
      <td>sitecode</td>
107
      <td>The sitecode that is used to create accession numbers.<br>
108
      DEPRECATED</td>
109
      <td>nceas</td>
110
    </tr>
111
    <tr>
112 104
      <td>accNumSeparator</td>
113 105
      <td>The separator that is used to separate the three parts 
114 106
          of the accession number: codename, sequence and revision number.
......
176 168
      <td>o=NCEAS,c=US</td>
177 169
    </tr>
178 170
    <tr>
171
      <td>referral</td>
172
      <td>The type of ldap referrals you want to use.  Eithe 'follow', 'throw' or 
173
      'none'.  See the ldap documentation for further information</td>
174
      <td>follow</td>
175
    </tr>
176
    <tr>
179 177
      <td>deltaT</td>
180 178
      <td>The default delta T used for <a href="./replication.html">replication</a>.</td>
181 179
      <td>60</td>
......
206 204
      <td>/opt/tomcat/webapps/knb/data</td>
207 205
    </tr>
208 206
    <tr>
209
      <td>dataport</td>
210
      <td>DEPRECATED</td>
211
      <td>4444</td>
207
      <td>certPath</td>
208
      <td>path to the SSL keys for secure transmissions.</td>
209
      <td>/opt/tomcat/webapps/metacat/lib</td>
212 210
    </tr>
213
    
214 211
  </table>
215 212
  
216 213
  <br>
docs/user/metacatquery.html
29 29
  <P>The Metacat Server provides 
30 30
  an interface for searching of metadata stored in the Metacat database.
31 31
  <P> <img alt="architecture diagram of a Metacat query" src="metadataquery.gif">
32
  <br><br><b>Steps to performing a query in Metacat</b>
32
  <br><br><b>Steps to perform a query in Metacat</b>
33 33
  <ol>
34
    <li>A pathquery document is created from the search criteria provide through
34
    <li>A pathquery document is created from the search criteria provided through
35 35
    the servlet parameters.</li>  
36 36
    <li>This pathquery document is sent to DBQuery where it 
37 37
    is processed and translated into SQL statements.</li>
......
160 160
      &lt;/resultset&gt;
161 161
    
162 162
  </pre>
163
  <p>The first element in the resultset is &lt;query&gt;.  As you may notice,
164
  its content is just the pathquery document.  The resultset always returns 
163
  <p>The first element in the resultset is &lt;query&gt;.  Its content is just 
164
  the pathquery document.  The resultset always returns 
165 165
  the pathquery document that created it in the &lt;query&gt; tag.  The next
166 166
  major tag is &lt;document&gt;.  Each XML document returned by the query
167
  is represented by a &lt;document&gt; tag.  The default information returned
168
  about a document are docid, docname, doctype, doctitle, createdate and  
167
  is represented by a &lt;document&gt; tag.  The default document information returned
168
  is docid, docname, doctype, doctitle, createdate and  
169 169
  updatedate.  The param tags are present if the document found contained
170 170
  the returnfield chosen in the pathquery document.  The name attribute of the
171 171
  param tag is the full path to the node specified by the returnfield.  &lt;relation&gt;
docs/user/metacatread.html
32 32
  wants to specify the requested document.  </p>
33 33
  <P> <img alt="architecture diagram of the Metacat read process" 
34 34
           src="metadataread.gif">  </p>
35
  <p>The documents are requested by <b>docid</b> servlet parameter:
36
  <ul>
37
     <li> By docid alone as: <br>
38
       <i>docid=NCEAS.54</i></li>
39
     <li> By Metacat URL as: <br>
40
       <i>docid=metacat://server.domain.com/metacat?docid=NCEAS.54</i></li>
41
     <li> By HTTP URL: <br>
42
       <i>docid=http://otherserver.domain.com/filename</i></li>
43
  </ul>
35
  <p>The documents are requested by the <b>docid</b> servlet parameter by specifying
36
  the document id that you wish to read.<br>
44 37
  </p>
45
  <p>There are two different output formats that a client can request from 
46
  Metacat: HTML or XML.  This is specified by the <b>qformat</b> parameter. <br>
47
  If more than one document is requested, the qformat does not matter,
48
  instead the documents are zipped together and retrieved to the client. <br>
49
  When <b>abstractpath</b> parameter along with docid parameter is
50
  specified as a XPath expression of the location of abstract data within
51
  XML document, the abstract data only are read and retrieved in XML format.
38
  <p>
39
    Metacat allows the dynamic transformation of read documents through the use
40
    of style-sets.  A style-set is an xsl stylesheet or a group of stylesheets
41
    that are specified in a config file.  The following is an example of a style-set
42
    config file:
43
  </p>
44
  <pre>
45
    &lt;?xml version="1.0"?&gt;
46
    &lt;style-set name="knb"&gt;
47
      &lt;default-style&gt;http://http://server.domain.com/metacat/style/ascii-treeview.xsl&lt;/default-style&gt;
48
      &lt;doctype publicid="-//NCEAS//resultset//EN"&gt;
49
        &lt;target publicid="-//W3C//HTML//EN"&gt;http://http://server.domain.com/metacat/style/resultset.xsl&lt;/target&gt;
50
      &lt;/doctype&gt;
51
      &lt;doctype publicid="-//NCEAS//login//EN"&gt;
52
        &lt;target publicid="-//W3C//HTML//EN"&gt;http://http://server.domain.com/metacat/style/login.xsl&lt;/target&gt;
53
      &lt;/doctype&gt;
54
      &lt;doctype publicid="-//NCEAS//eml-dataset-2.0//EN"&gt;
55
        &lt;target publicid="-//W3C//HTML//EN"&gt;http://http://server.domain.com/metacat/style/eml-dataset-display.xsl&lt;/target&gt;  
56
      &lt;/doctype&gt;
57
      &lt;doctype publicid="-//NCEAS//eml-dataset//EN"&gt;
58
        &lt;target publicid="-//W3C//HTML//EN"&gt;http://http://server.domain.com/metacat/style/eml-dataset-display.xsl&lt;/target&gt;  
59
      &lt;/doctype&gt;
60
      &lt;doctype publicid="-//NCEAS//eml-resource//EN"&gt;
61
        &lt;target publicid="-//W3C//HTML//EN"&gt;http://http://server.domain.com/metacat/style/eml-dataset-display.xsl&lt;/target&gt;  
62
      &lt;/doctype&gt;      
63
      &lt;doctype publicid="-//ecoinformatics.org//eml-dataset-2.0.0beta4//EN"&gt;
64
        &lt;target publicid="-//W3C//HTML//EN"&gt;http://http://server.domain.com/metacat/style/eml-dataset-display.xsl&lt;/target&gt;  
65
      &lt;/doctype&gt;
66
    &lt;/style-set&gt;
67
  </pre>
52 68

  
53
  <p>For example, if a user wanted to request document NCEAS.54 and have it
54
     returned as HTML, the servlet call would look like this: <br>
55
     <i>http://server.domain.com/knb/servlet/metacat?action=read&amp;qformat=html&amp;docid=NCEAS.54</i>
56
     <br>
57
     Another way to request a document is by Metacat URL.  the URL would look like: <br>
58
     <i>http://server.domain.com/knb/servlet/metacat?
59
       action=read&qformat=xml&amp;docid=metacat://server.domain.com/metacat?docid=NCEAS.54</i>
60
     <br>
61
     Note that this url requests that the document be delivered in xml instead of html.
69
  <p>
70
    Whenever a read action is requested from Metacat, you can also provide a qformat parameter.
71
    This qformat parameter should be the name of the style-set that you wish to use
72
    to transform the document you are requesting.  Note that the value that you set
73
    qformat to must equal the &lt;style-set&gt; name parameter.
62 74
  </p>
63 75
  <p>
64
    Metacat URLs as in the second example become useful when more than one Metacat
65
    server is being run at one site or a bunch of sites are replicating between each
66
    other and you want to specify a document at a precise location.
67
    <!--  <a href="./packages.html">Package</a>
68
    files exclusively use Metacat URLs for document identification. -->
76
    A default style-set can be set in the metacat.properties file.  If qformat
77
    is set to 'html', Metacat will use the default.  If qformat is set to 'xml',
78
    Metacat will return the XML document untransformed.
69 79
  </p>
70

  
71 80
  <br>
72 81
  <a href="./metacatquery.html">Back</a> | <a href="./metacattour.html">Home</a> | 
73 82
  <a href="./saxparser.html">Next</a>
docs/user/metacat.html
26 26
      </td>
27 27
    </tr>
28 28
  </table>
29
  <P>Metacat Server stores arbitrary XML 
30
  documents without foreknowledge of the metadata schema in relational 
31
  database using DOM approach. Metacat also performs optimized free-text 
29
  <P>The Metacat Server stores arbitrary XML 
30
  documents in a relational 
31
  database without foreknowledge of the document schema.  It does this by implementing
32
  the DOM within the table structure of the relational database.
33
  Metacat also performs optimized free-text 
32 34
  and structured 
33
  searches across the entire metadata collection. Metacat Server provides 
34
  standardized interface to client software for document processing, storing 
35
  searches across the entire document collection. Metacat provides 
36
  standardized interfaces to client software for document processing, storing 
35 37
  and searching. 
36 38

  
37 39
  <P> <img alt="Structural diagram of Metacat architecture" src="metacat.gif">
docs/user/metacatdom.html
27 27
    </tr>
28 28
  </table>
29 29
  <P>In the Metacat DOM implementation XML documents 
30
  are disassembled in their composing nodes. All nodes are stored as records 
31
  in relational database tables. The structure of each XML document is preserved 
32
  by saving parent-child relationship between the nodes.
30
  are disassembled into their composite nodes. All nodes are stored as records 
31
  in the database tables. The structure of each XML document is preserved 
32
  by saving the parent-child relationship between the nodes.
33 33
    <ul>
34 34
    <li> Each XML document in the Metacat database starts with one root node of 
35 35
    type DOCUMENT. All other nodes in the document are its children. 
docs/user/metacatload.html
26 26
      </td>
27 27
    </tr>
28 28
  </table>
29
  <P>Metacat Server provides functionality for inserting, updating, and deleting
29
  <P>Metacat provides functionality for inserting, updating, and deleting
30 30
  XML documents in the database. Inserted or updated documents are read, checked 
31 31
  for validity, decomposed into nodes and inserted into the db. Document validity 
32 32
  is checked if a valid DTD is provided.
docs/user/ldap.html
101 101
    </p>
102 102
    
103 103
  <br>
104
  <a href="./xmlindex.html">Back</a> | <a href="./metacattour.html">Home</a> | 
104
  <a href="./acontrol.html">Back</a> | <a href="./metacattour.html">Home</a> | 
105 105
  <a href="./metacatout.html">Next</a>
106 106
</BODY>
107 107
</HTML>
docs/user/metacatdb.html
27 27
    </tr>
28 28
  </table>
29 29

  
30
  <P>The Metacat Database stores the structure and data of any arbitrary 
31
  xml document. Metacat DB uses the DOM 
30
  <P>Metacat's backend database stores the structure and data of any arbitrary 
31
  XML document. The Metacat database uses the DOM 
32 32
  approach to store XML documents as a hierarchy of nodes. All nodes are stored 
33 33
  as records in database tables. The hierarchical relationship between the nodes 
34 34
  is saved to preserve the structure of the documents.</p>
......
54 54
    server replicates to or from.</li>
55 55
    <li><b>xml_relation</b> contains any relation information inserted by a 
56 56
    <a href="./packages.html">Package</a> document.</li>
57
    <li><b>xml_access</b> contains all Access Control List (ACL) information 
57
    <li><b>xml_access</b> contains all <a href="acontrol.html">Access Control List</a> (ACL) information 
58 58
    relevent to a document.</li>
59 59
    <li><b>xml_catalog</b>  contains catalog information that represents DTDs 
60 60
    and XSL stylesheets that are registered with the system.</li>
docs/user/metacatout.html
36 36
  <img src="xmltransform.gif">
37 37
  
38 38
  <p>Metacat can be set on the fly to either transform or not transform a resultset
39
  from XML.  This is achieved by setting the 'qformat' servlet parameter to 'html'
39
  from XML.  This is achieved by setting the 'qformat' servlet parameter to the name
40
  of a <a href="metacatread.html">style-set</a> or to 'html'
40 41
  or 'xml'.  When qformat is set to html, Metacat will transform the resultset based 
41
  on the stylesheet specified in the resultStyleURL of the 
42
  <a href="./properties.html">Metacat Properties</a> file.  This XSL stylesheet
42
  on the default style-set configured in the 
43
  <a href="./properties.html">Metacat Properties</a> file.  This style-set
43 44
  defines the rules for how to translate the XML tags into HTML tags.  
44 45
  </p>
45
  <p>A user can specify that a certain doctype is always transformed using a 
46
  specific stylesheet by registering that stylesheet in the Metacat Catalog.  
47
  The Catalog is stored in the database table xml_catalog and contains a
48
  list of doctypes and the stylesheets used to transform them.  If a doctype 
49
  has an assigned stylesheet, whenever a document of that type is "read" from 
50
  Metacat and qformat is set to HTML, the document will be transformed using
51
  the assigned stylesheet.
52
  </p>
53 46
  
54 47
  <br>
55
  <a href="./acontrol.html">Back</a> | <a href="./metacattour.html">Home</a> | 
48
  <a href="./ldap.html">Back</a> | <a href="./metacattour.html">Home</a> | 
56 49
  <a href="./metacatapi.html">Next</a>
57 50
  
58 51
</BODY>
docs/user/index.html
46 46
     The Metacat database models XML documents as a DOM tree, basically 
47 47
     decomposing the nodes of the XML document and storing the node data
48 48
     as a series of records in a relational database via a JDBC connection.
49
     At this point, only Oracle has been tested as a backend database, but
50
     we have avoided Oracle specific features in order to maintain portability
49
     At this point, only Oracle and PostgreSQL have been tested as a backend databases, but
50
     we have avoided RDBMS specific features in order to maintain portability
51 51
     to other relational databases.
52 52
  </p>
53 53
  <p>

Also available in: Unified diff