Project

General

Profile

metacat / docs / user / metacatapi.html @ 4604

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 4604 2008-11-20 19:51:01Z daigle $'
11
  * 
12
  * October Meeting SDSC, 2000
13
-->
14
<HTML>
15
<HEAD>
16
<TITLE>Metacat</TITLE>
17
<link rel="stylesheet" type="text/css" href="./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>spatial_query</td>
102
      <td>
103
      <ul>
104
        <li>xmax - max x spacial coordinate</li>
105
        <li>ymax - max y spacial coordinate</li>
106
        <li>xmin - min x spacial coordinate</li>
107
        <li>ymin - min y spacial coordinate</li>
108
      </ul>
109
      </td>
110
      <td>Perform a spatial query.  These queries may include any of the 
111
          queries supported by the WFS / WMS standards.</td>
112
    </tr>
113
    <tr>
114
      <td>read</td>
115
      <td>
116
      <ul>
117
        <li>docid - the docid of the document to read</li>
118
        <li>qformat - the format to return the document in.  Possible values 
119
        are: html, xml</li>
120
      </ul>
121
      </td>
122
      <td>Get docid from the database and return it in qformat form.</td>
123
    </tr>
124
    <tr>
125
      <td>readinlinedata</td>
126
      <td>
127
      <ul>
128
        <li>inlinedataid - the id of the inline data to read</li>
129
      </ul>
130
      </td>
131
      <td>Read inline data only.</td>
132
    </tr>
133
    <tr>
134
      <td>insert</td>
135
      <td>
136
        <ul>
137
          <li>docid - the user defined docid to assign to the new XML document.</li>
138
          <li>doctext - the text of the XML document to insert</li>
139
        </ul>
140
      </td>
141
      <td>Insert an XML document into the database.</td>
142
    </tr>
143
    <tr>
144
      <td>insertmultipart</td>
145
      <td>
146
        <ul>
147
          <li>docid - the user defined docid to assign to the new XML document.</li>
148
          <li>doctext - the text of the XML document to insert</li>
149
        </ul>
150
      </td>
151
      <td>insert an xml document into the database using multipart encoding.</td>
152
    </tr>
153
    <tr>
154
      <td>update</td>
155
      <td>
156
      <ul>
157
        <li>docid - the docid of the document to update</li>
158
        <li>doctext - the text with which to update the XML document</li>
159
      </ul>
160
      </td>
161
      <td>Overwrite an XML document with a new one and give the new one 
162
          the same docid but with next revision number.</td>
163
    </tr>
164
    <tr>
165
      <td>upload</td>
166
      <td>
167
      <ul>
168
        <li>docid - the docid of the data document to upload</li>
169
        <li>datafile - the data document to upload</li>
170
      </ul>
171
      </td>
172
      <td>Upload (insert or update) a data document into metacat. Data files are stored on 
173
               metacat and may be in any format (binary or text), but they are all
174
               treated as if they were binary.</td>
175
    </tr>
176
    <tr>
177
      <td>delete</td>
178
      <td>
179
        <ul>
180
          <li>docid - the docid of the document to delete</li>
181
        </ul>
182
      </td>
183
      <td>Delete the specified docid from the database.</td>
184
    </tr>
185
    <tr>
186
      <td>setaccess</td>
187
      <td>
188
        <ul>
189
          <li>docid - the docid of the document whose access we want to change</li>
190
          <li>principal - the user or group whose permissions want to change</li>
191
          <li>permission - the permission we want to set (read, write, all)</li>
192
          <li>permType - the type of permission to set (allow, deny)</li>
193
          <li>permOrder - the order to apply the permission (allowFirst, denyFirst)</li>
194
        </ul>
195
      </td>
196
      <td>Change access permissions for a user on a document.</td>
197
    </tr>
198
    <tr>
199
      <td>validate</td>
200
      <td>
201
      <ul>
202
        <li>docid - the docid of the document to validate</li>
203
        <li>valtext - the DTD by which to validate this document</li>
204
      </ul>
205
      </td>
206
      <td>Validate docid against its DTD.</td>
207
    </tr>
208
    <tr>
209
      <td>getaccesscontrol</td>
210
      <td>
211
      <ul>
212
        <li>docid - the docid of the document to get the ACL for</li>
213
      </ul>
214
      </td>
215
      <td>Get ACL for document with that docid</td>
216
    </tr>
217
    <tr>
218
      <td>getprincipals</td>
219
      <td>none</td>
220
      <td>Get all users and groups in the current authentication schema</td>
221
    </tr>
222
    <tr>
223
      <td>getdoctypes</td>
224
      <td>none</td>
225
      <td>Get all doctypes currently available in Metacat Catalog System.</td>
226
    </tr>
227
    <tr>
228
      <td>getdtdschema</td>
229
      <td>
230
        <ul>
231
          <li>doctype - the doctype which DTD or XMLSchema file to read.</td>
232
        </ul>
233
      </td>
234
      <td>Read DTD or XMLSchema file for the specified doctype.</td>
235
    </tr>
236
    <tr>
237
      <td>getdataguide</td>
238
      <td>
239
        <ul>
240
          <li>doctype - the doctype for which to get the data guide</li> <br>
241
          <i><b> Deprecated. </b></i> Use getdtdschema action instead.
242
        </ul>
243
      </td>
244
      <td>Read a dataguide for doctype.</td>
245
    </tr>
246
    <tr>
247
      <td>getlastdocid</td>
248
      <td>
249
        <ul>
250
          <li>username - the user's login name which last docid to get.</td>
251
        </ul>
252
      </td>
253
      <td>Get the latest docid with rev number used by user.</td>
254
    </tr>
255
    <tr>
256
      <td>getalldocids</td>
257
      <td>
258
        <ul>
259
          <li>scope - a string used to match a range of docids in a SQL LIKE statement.</td>
260
        </ul>
261
      </td>
262
      <td>retrieves a list of all docids registered with the system.</td>
263
    </tr>
264
    <tr>
265
      <td>isregistered</td>
266
      <td>
267
        <ul>
268
          <li>docid - the docid of the document to check for.</td>
269
        </ul>
270
      </td>
271
      <td>checks if an individual document exists in either the xml_documents
272
          or xml_revisions tables.</td>
273
    </tr>
274
    <tr>
275
      <td>getrevisionanddoctype</td>
276
      <td>
277
        <ul>
278
          <li>docid - the docid of the document to check for.</td>
279
        </ul>
280
      </td>
281
      <td>Return the revision and doctype of a document. The output is String 
282
      that looks like "rev;doctype"</td>
283
    </tr>
284
    <tr>
285
      <td>getversion - get Metacat version.</td>
286
      <td>none</td>
287
      <td>Returns the current version of Metacat as XML.</td>
288
    </tr>
289
    <tr>
290
      <td>protocoltest</td>
291
      <td>
292
        <ul>
293
          <li>url - the url to test against the protocol handler</li>
294
        </ul>
295
      </td>
296
      <td>Test the protocol handlers installed for metacat:// URLs.</td>
297
    </tr>
298
    <tr>
299
      <td>export</td>
300
      <td>
301
        <ul>
302
          <li>docid - the docid of the package you wish to export</li>
303
        </ul>
304
      </td>
305
      <td>
306
        Exports a data package in a zip file.
307
      </td>
308
    </tr>
309
    <tr>
310
      <td>getlog</td>
311
      <td>
312
        <ul>
313
            <li>ipaddress - the internet protocol address for the event</li>
314
            <li>principal - the principal for the event (a username, etc)</li>
315
            <li>docid - the identifier of the document to which the event applies</li>
316
            <li>event - the string code for the event</li>
317
            <li>start - beginning of date range for query</li>
318
            <li>end - end of date range for query</li>
319
        </ul>
320
      </td>
321
      <td>Print a report from the Metacat event log.</td>
322
    </tr>
323
    <tr>
324
      <td>getloggedinuserinfo</td>
325
      <td>none</td>
326
      <td>Get user info for the currently logged in user.</td>
327
    </tr>
328
  </table>
329
  
330
  <br>
331
  <b><a href="./replication.html">MetacatReplication</a> Parameters</b>
332
    <table border="1">
333
    <tr>
334
      <td><b>Action</b></td>
335
      <td><b>Supplemental Parameters</b></td>
336
      <td><b>Description</b></td>
337
    </tr>
338
    <tr>
339
      <td>forcereplicate</td>
340
      <td>
341
        <ul>
342
          <li>server - The server to which this document is being sent</li>
343
          <li>docid - The docid of the document to send</li>
344
          <li>dbaction - DEFAULTS TO UPDATE - The action to perform on the 
345
          document.  INSERT or UPDATE.</li>
346
        </ul>
347
      </td>
348
      <td>Force this server to get docid from the remote host.</td>
349
    </tr>
350
    <tr>
351
      <td>getall</td>
352
      <td>none</td>
353
      <td>Forces the local server to check all known servers for updated
354
      documents.</td>
355
    </tr>
356
    <tr>
357
      <td>getcatalog</td>
358
      <td>none</td>
359
      <td>Sends the contents of the xml_catalog table encoded in XML.</td>
360
    </tr>
361
    <tr>
362
      <td>getlock</td>
363
      <td>
364
        <ul>
365
          <li>docid - the docid to get the lock for</li>
366
          <li>updaterev - the revision number of docid</li>
367
        </ul>
368
      </td>
369
      <td>Request a lock on docid.</td>
370
    </tr>
371
    <tr>
372
      <td>gettime</td>
373
      <td>none</td>
374
      <td>Return the local time on this server.</td>
375
    </tr>
376
    <tr>
377
      <td>servercontrol</td>
378
      <td>
379
        <ul>
380
          <li>subaction - The replication control to be performed.  Possible
381
          values: 
382
            <ul>
383
              <li>add - add a new server to the replication list</li>
384
              <li>delete - remove a server from the replication list</li>
385
              <li>list - list all of the servers currently in the server list</li>
386
            </ul>
387
          <li>replicate - a boolean flag (1 or 0) which determines if this
388
          server is to copy files from the newly added server.</li>
389
          <li>server - the server to add/delete</li>
390
        </ul>
391
      </td>
392
      <td>Perform subaction on the Replication daemon.</td>
393
    </tr>
394
    <tr>
395
      <td>read</td>
396
      <td>
397
        <ul>
398
          <li>docid - the docid to read</li>
399
        </ul>
400
      </td>
401
      <td>Sends docid to the remote host.</td>
402
    </tr>
403
    <tr>
404
      <td>start</td>
405
      <td>
406
        <ul>
407
          <li>rate - DEFAULTS TO 1000 - The rate (in seconds) at which you want
408
          the replication daemon to check for updated documents.  The value
409
          cannot be less than 30.</li>
410
        </ul>
411
      </td>
412
      <td>Start the Replication daemon with a time interval of deltaT.</td>
413
    </tr>
414
    <tr>
415
      <td>stop</td>
416
      <td>none</td>
417
      <td>Stop the Replication daemon.</td>
418
    </tr>
419
    <tr>
420
      <td>update</td>
421
      <td>none</td>
422
      <td>Send a list of all documents on the local server along with their
423
      revision numbers.</td>
424
    </tr>
425
  </table>
426
  <br>
427
  <a href="./metacatout.html">Back</a> | <a href="./metacattour.html">Home</a> | 
428
  <a href="./packages.html">Next</a>
429
</BODY>
430
</HTML>
431