Project

General

Profile

1
<!--
2
  * Metacatapi.html
3
  *
4
  *      Authors: Jivka Bojilova
5
  *    Copyright: 2000 Regents of the University of California and the
6
  *               National Center for Ecological Analysis and Synthesis
7
  *  For Details: http://www.nceas.ucsb.edu/
8
  *      Created: 2000 April 5
9
  *      Version: 0.01
10
  *    File Info: '$Id: metacatapi.html 878 2001-12-18 18:11:42Z berkley $'
11
  * 
12
  * October Meeting SDSC, 2000
13
-->
14
<HTML>
15
<HEAD>
16
<TITLE>Metacat</TITLE>
17
<link rel="stylesheet" type="text/css" href="@docrooturl@default.css">
18
</HEAD> 
19
<BODY>
20
  <table width="100%">
21
    <tr>
22
      <td class="tablehead" colspan="2"><p class="label">Metacat High Level API</p></td>
23
      <td class="tablehead" colspan="2" align="right">
24
        <a href="./metacatout.html">Back</a> | <a href="./metacattour.html">Home</a> | 
25
        <a href="./packages.html">Next</a>
26
      </td>
27
    </tr>
28
  </table>
29
  <p>
30
      <b>Multiple client interface</b> <br>
31
      Since Metacat Servlet is a subclass of HttpServlet, this allows any client
32
      to communicate with Metacat by essentially passing a URL with embedded
33
      servlet parameters.
34
      Metacat Servlet provides an HTTP Interface and can handle GET and POST 
35
      requests. HTTP requests are sent from the the Client application and contain 
36
      a number of parameters. These parameters, in form of name/value pairs, provide 
37
      input data for the Servlet and also provide the Servlet any extra information it 
38
      needs to handle the request. </p>
39
  <P> <b>Extensions of HttpServlet</b> <br>
40
      Metacat Server adds the functionality for writing, quering, and reading of 
41
      XML stored in the Metacat Database as well functions for validating and 
42
      transforming XML documents. </p>
43
  <b>MetacatServlet Parameters</b>
44
  <table border="1">
45
    <tr>
46
      <td><b>Action</b></td>
47
      <td><b>Supplemental Parameters</b></td>
48
      <td><b>Description</b></td>
49
    </tr>
50
    <tr>
51
      <td>login</td>
52
      <td>
53
        <ul>
54
          <li>username - the user's login name</li>
55
          <li>password - the user's password</li>
56
        </ul>
57
      </td>
58
      <td>Log the user in.</td>
59
    </tr>
60
    <tr>
61
      <td>logout</td>
62
      <td>none</td>
63
      <td>Log the current user out and destroy the associated session.</td>
64
    </tr>
65
    <tr>
66
      <td>query</td>
67
      <td>
68
        <ul>
69
          <li>returndoctype - the doctype that you wish to use for your 
70
          <a href="./packages.html">Package View</a></li>
71
          <li>qformat - the format that you wish to return the resultset in.  
72
          Possible values are 'html' or 'xml'.</li>
73
          <li>querytitle - OPTIONAL - the title of the query</li>
74
          <li>doctype - OPTIONAL - if doctype is specified, the search is limited
75
          only to the doctype(s) specified.</li>
76
          <li>returnfield - a custom field to be returned by any hit document.  
77
          This is explained in more detail in <a href="./metacatquery.html">
78
          Queries and Results</a>.</li>
79
          <li>operator - the boolean operator to apply to the query - Possible
80
          values are: UNION or INTERSECT</li>
81
          <li>searchmode - the type of search to be performed.  Possible values
82
          are: contains, starts-with, ends-with, equals, isnot-equal, greater-than,
83
          less-than, greater-than-equals, less-than-equals.</li>
84
          <li>anyfield - a freetext search variable.  A value placed in this 
85
          parameter will be searched for in any document in any node.</li>
86
        </ul>
87
      </td>
88
      <td>Perform a free text query.</td>
89
    </tr>
90
    <tr>
91
      <td>squery</td>
92
      <td>
93
      <ul>
94
        <li>query - the text of the pathquery document that is being sent to the
95
        server</li>
96
      </ul>
97
      </td>
98
      <td>Perform a structured query.</td>
99
    </tr>
100
    <tr>
101
      <td>read</td>
102
      <td>
103
      <ul>
104
        <li>docid - the docid of the document to read</li>
105
        <li>qformat - the format to return the document in.  Possible values 
106
        are: html, xml</li>
107
      </ul>
108
      </td>
109
      <td>Get docid from the database and return it in qformat form.</td>
110
    </tr>
111
    <tr>
112
      <td>insert</td>
113
      <td>
114
        <ul>
115
          <li>docid - the user defined docid to assign to the new document.</li>
116
          <li>doctext - the text of the document to insert</li>
117
        </ul>
118
      </td>
119
      <td>Insert doctext into the database.</td>
120
    </tr>
121
    <tr>
122
      <td>update</td>
123
      <td>
124
      <ul>
125
        <li>docid - the docid of the document to update</li>
126
        <li>doctext - the text with which to update the document</li>
127
      </ul>
128
      </td>
129
      <td>Overwrite a document with a new one and give the new one 
130
          the same docid but with next revision number.</td>
131
    </tr>
132
    <tr>
133
      <td>delete</td>
134
      <td>
135
        <ul>
136
          <li>docid - the docid of the document to delete</li>
137
        </ul>
138
      </td>
139
      <td>Delete the specified docid from the database.</td>
140
    </tr>
141
    <tr>
142
      <td>validate</td>
143
      <td>
144
      <ul>
145
        <li>docid - the docid of the document to validate</li>
146
        <li>valtext - the DTD by which to validate this document</li>
147
      </ul>
148
      </td>
149
      <td>Validate docid against its DTD.</td>
150
    </tr>
151
    <tr>
152
      <td>getaccesscontrol</td>
153
      <td>
154
      <ul>
155
        <li>docid - the docid of the document to get the ACL for</li>
156
      </ul>
157
      </td>
158
      <td>Get ACL for document with that docid</td>
159
    </tr>
160
    <tr>
161
      <td>getprincipals</td>
162
      <td>none</td>
163
      <td>Get all users and groups in the current authentication schema</td>
164
    </tr>
165
    <tr>
166
      <td>getdoctypes</td>
167
      <td>none</td>
168
      <td>Get all doctypes currently available in Metacat Catalog System.</td>
169
    </tr>
170
    <tr>
171
      <td>getdtdschema</td>
172
      <td>
173
        <ul>
174
          <li>doctype - the doctype which DTD or XMLSchema file to read.</td>
175
        </ul>
176
      </td>
177
      <td>Read DTD or XMLSchema file for the specified doctype.</td>
178
    </tr>
179
    <tr>
180
      <td>getdataguide</td>
181
      <td>
182
        <ul>
183
          <li>doctype - the doctype for which to get the data guide</li> <br>
184
          <i><b> Deprecated. </b></i> Use getdtdschema action instead.
185
        </ul>
186
      </td>
187
      <td>Read a dataguide for doctype.</td>
188
    </tr>
189
    <tr>
190
      <td>getlastdocid</td>
191
      <td>
192
        <ul>
193
          <li>username - the user's login name which last docid to get.</td>
194
        </ul>
195
      </td>
196
      <td>Get the latest docid with rev number used by user.</td>
197
    </tr>
198
    <tr>
199
      <td>protocoltest</td>
200
      <td>
201
        <ul>
202
          <li>url - the url to test against the protocol handler</li>
203
        </ul>
204
      </td>
205
      <td>Test the protocol handlers installed for metacat:// URLs.</td>
206
    </tr>
207
  </table>
208
  
209
  <!--
210
  <TABLE border=1 width=700>
211
  <TR>
212
    <TH WIDTH="50%">Metacat Server Interface functions</TH>
213
    <TH WIDTH="50%">Parameter list</TH>
214
  <TR>
215
    <TD><small>Structured query search through Metacat DB </TD>
216
    <TD><small>action=squery <br>
217
      query <br>
218
      returndoc <br>
219
      username <br>
220
      groupname </TD>
221
  <TR>
222
    <TD><small>Structured query search. Query parts provided in the parameter 
223
    list </TD>
224
    <TD><small>action=query <br>
225
      meta_file_id <br>
226
      querytitle <br>
227
      doctype <br>
228
      returnfield <br>
229
      operator <br>
230
      casesensitive <br>
231
      searchmode <br>
232
      anyfield </TD>
233
  <TR>
234
    <TD><small> Read XML document from Metacat DB, transform into qformat 
235
    and return it </TD>
236
    <TD><small> action=read <br>
237
      docid <br>
238
      qformat </TD>
239
  <TR>
240
    <TD><small> Read XML document <br>
241
      - from Metacat DB if url=Metacat://... <br>
242
      - from Internet if url=http:// <br>
243
      Transform into qformat and return it </TD>
244
    <TD><small>  action=read <br>
245
      docid <br>
246
      qformat </TD>
247
  <TR>
248
    <TD><small> Read abstract data of a document and return it </TD>
249
    <TD><small> action=getabstract <br>
250
      abstractpath <br>
251
      docid </TD>
252
  <TR>
253
    <TD><small> Write XML document into Metacat DB </TD>
254
    <TD><small> action=insert <br>
255
      docid <br>
256
      doctext <br>
257
      username <br>
258
      groupname </TD>
259
  <TR>
260
    <TD><small> Modify existing in Metacat Db XML document with new content 
261
    provided </TD>
262
    <TD><small> action=update <br>
263
      docid <br>
264
      doctext <br>
265
      username <br>
266
      groupname </TD>
267
  <TR>
268
    <TD><small> Delete existing in Metacat Db XML document </TD>
269
    <TD><small> action=delete <br>
270
      docid <br>
271
      username <br>
272
      groupname </TD>
273
  <TR>
274
    <TD><small> Validate XML document </TD>
275
    <TD><small>  action=validate <br>
276
      docid <br>
277
      valtext <br>
278
      username <br>
279
      groupname </TD>
280
  <TR>
281
    <TD><small> Read XML document from Metacat Db and related documents if 
282
    they exist and return them in zip file </TD>
283
    <TD><small> action=getdatadoc <br>
284
      docid <br>
285
      relation </TD>
286
  <TR>
287
    <TD><small> Read all different document types currently available in 
288
    Metacat Db </TD>
289
    <TD><small> action=getdoctypes </TD>
290
  <TR>
291
    <TD><small> Read Data Guide for specified doctype </TD>
292
    <TD><small> action=getdataguide <br>
293
      doctype </TD>
294
  <TR>
295
    <TD><small> Login to Metacat Server </TD>
296
    <TD><small>  action=login <br>
297
      username <br>
298
      password </TD>
299
  <TR>
300
    <TD><small> Logout from Metacat Server </TD>
301
    <TD><small> action=logout </TD>
302
  </TABLE>
303

    
304
  <P><b>HTTP parameters for Metacat Server </b>
305
  <TABLE border=1>
306
  <TR>
307
    <TH>Name</TH>
308
    <TH>Value</TH>
309
  <TR>
310
    <TD VALIGN=TOP>&nbsp;action</TD>
311
    <TD>&nbsp;squery <br>
312
        &nbsp;query <br>
313
        &nbsp;getdocument <br>
314
        &nbsp;getrelateddocument <br>
315
        &nbsp;getabstract <br>
316
        &nbsp;insert <br>
317
        &nbsp;update <br>
318
        &nbsp;delete <br>
319
        &nbsp;validate <br>
320
        &nbsp;getdatadoc <br>
321
        &nbsp;getdoctypes <br>
322
        &nbsp;getdataguide <br>
323
        &nbsp;login <br>
324
        &nbsp;logout </TD>
325
  <TR>
326
    <TD>&nbsp;query</TD>
327
    <TD>&nbsp;<i>XML text of query that conforms to pathquery.dtd</i> </TD>
328
  <TR>
329
    <TD>&nbsp;returndoc</TD>
330
    <TD>&nbsp;<i>array of doctypes to backtrack against</i> </TD>
331
  <TR>
332
    <TD>&nbsp;doctype</TD>
333
    <TD>&nbsp;<i>document type list</i> </TD>
334
  <TR>
335
    <TD>&nbsp;docid</TD>
336
    <TD>&nbsp;<i>docid of document</i></TD>
337
  <TR>
338
    <TD>&nbsp;doctext</TD>
339
    <TD>&nbsp;<i>XML text of document to be load into db</i> </TD>
340
  <TR>
341
    <TD>&nbsp;valtext</TD>
342
    <TD>&nbsp;<i>XML text of document to be validated</i> </TD>
343
  <TR>
344
    <TD>&nbsp;abstractpath</TD>
345
    <TD>&nbsp;<i>XML path to the abstract node to be read</i> </TD>
346
  <TR>
347
    <TD>&nbsp;url</TD>
348
    <TD>&nbsp;<i>URL to document. It can be of type Metacat or http</i> </TD>
349
  <TR>
350
    <TD>&nbsp;relation</TD>
351
    <TD>&nbsp;<i>List of URLs to documents. They can be of type Metacat or 
352
    http</i> </TD>
353
  <TR>
354
    <TD>&nbsp;qformat</TD>
355
    <TD>&nbsp;xml <br>&nbsp;html </TD>
356
  <TR>
357
    <TD>&nbsp;username</TD>
358
    <TD>&nbsp;<i>username for authentication and connection to the server</i></TD>
359
  <TR>
360
    <TD>&nbsp;password</TD>
361
    <TD>&nbsp;<i>user's password for authentication</i> </TD>
362
  </TABLE> 
363
  -->
364
  <br>
365
  <b><a href="./replication.html">MetacatReplication</a> Parameters</b>
366
    <table border="1">
367
    <tr>
368
      <td><b>Action</b></td>
369
      <td><b>Supplemental Parameters</b></td>
370
      <td><b>Description</b></td>
371
    </tr>
372
    <tr>
373
      <td>forcereplicate</td>
374
      <td>
375
        <ul>
376
          <li>server - The server to which this document is being sent</li>
377
          <li>docid - The docid of the document to send</li>
378
          <li>dbaction - DEFAULTS TO UPDATE - The action to perform on the 
379
          document.  INSERT or UPDATE.</li>
380
        </ul>
381
      </td>
382
      <td>Force this server to get docid from the remote host.</td>
383
    </tr>
384
    <tr>
385
      <td>getall</td>
386
      <td>none</td>
387
      <td>Forces the local server to check all known servers for updated
388
      documents.</td>
389
    </tr>
390
    <tr>
391
      <td>getcatalog</td>
392
      <td>none</td>
393
      <td>Sends the contents of the xml_catalog table encoded in XML.</td>
394
    </tr>
395
    <tr>
396
      <td>getlock</td>
397
      <td>
398
        <ul>
399
          <li>docid - the docid to get the lock for</li>
400
          <li>updaterev - the revision number of docid</li>
401
        </ul>
402
      </td>
403
      <td>Request a lock on docid.</td>
404
    </tr>
405
    <tr>
406
      <td>gettime</td>
407
      <td>none</td>
408
      <td>Return the local time on this server.</td>
409
    </tr>
410
    <tr>
411
      <td>servercontrol</td>
412
      <td>
413
        <ul>
414
          <li>subaction - The replication control to be performed.  Possible
415
          values: 
416
            <ul>
417
              <li>add - add a new server to the replication list</li>
418
              <li>delete - remove a server from the replication list</li>
419
              <li>list - list all of the servers currently in the server list</li>
420
            </ul>
421
          <li>replicate - a boolean flag (1 or 0) which determines if this
422
          server is to copy files from the newly added server.</li>
423
          <li>server - the server to add/delete</li>
424
        </ul>
425
      </td>
426
      <td>Perform subaction on the Replication daemon.</td>
427
    </tr>
428
    <tr>
429
      <td>read</td>
430
      <td>
431
        <ul>
432
          <li>docid - the docid to read</li>
433
        </ul>
434
      </td>
435
      <td>Sends docid to the remote host.</td>
436
    </tr>
437
    <tr>
438
      <td>start</td>
439
      <td>
440
        <ul>
441
          <li>rate - DEFAULTS TO 1000 - The rate (in seconds) at which you want
442
          the replication daemon to check for updated documents.  The value
443
          cannot be less than 30.</li>
444
        </ul>
445
      </td>
446
      <td>Start the Replication daemon with a time interval of deltaT.</td>
447
    </tr>
448
    <tr>
449
      <td>stop</td>
450
      <td>none</td>
451
      <td>Stop the Replication daemon.</td>
452
    </tr>
453
    <tr>
454
      <td>update</td>
455
      <td>none</td>
456
      <td>Send a list of all documents on the local server along with their
457
      revision numbers.</td>
458
    </tr>
459
  </table>
460
  <br>
461
  <a href="./metacatout.html">Back</a> | <a href="./metacattour.html">Home</a> | 
462
  <a href="./packages.html">Next</a>
463
</BODY>
464
</HTML>
465

    
(17-17/45)