Project

General

Profile

1
Accessing and Submitting Metadata and Data
2
==========================================
3

    
4
.. contents::
5

    
6
The Metacat repository can be accessed and updated using a number of tools, 
7
including: 
8

    
9
* the Registry, Metacat's optional Web interface
10
* user-created HTML forms 
11
* Metacat's EarthGrid API
12
* existing clients, such as KNB's Morpho application, designed to help 
13
  scientists create, edit, and manage metadata
14
* user-created desktop clients that take advantage of Metacat's Java API.
15

    
16
In this section, we will look at how to take advantage of these tools to 
17
customize Metacat for your user-base.
18

    
19
A Brief Note about How Information is Stored
20
--------------------------------------------
21
Metacat stores XML files as a hierarchy of nodes, where each node is stored as 
22
records in database tables. Because many XML data schemas are broken up into 
23
multiple DTDs requiring multiple XML files that are related but stored 
24
separately in the system, the system uses "packages" to link related but 
25
separate documents. Packaged documents contain information that shows how they 
26
are related to eachother, essentially stating that file A has a relationship 
27
to file B, etc. A package file also allows users to link metadata files to the 
28
data files they describe. For more information about the structure of data 
29
packages and how XML documents and data are stored in Metacat, please see the 
30
developer's documentation.
31

    
32
Using the Registry
33
------------------
34
Metacat's optional Registry provides a simple Web-based interface for creating, 
35
editing, and submitting metadata to the Metacat repository (screenshot below). The 
36
interface includes help documentation, and can be customized using Metacat's 
37
configuration settings. The Registry also includes an administrative interface 
38
for managing LDAP user accounts, which is useful if you are using LDAP as your 
39
Metacat authentication system. Note that you must be running your own LDAP 
40
server if you wish to use the LDAP Web interface. If you do not have your own 
41
LDAP server, you can create and manage new accounts on the KNB website 
42
(http://knb.ecoinformatics.org/). Please note that at this time, the Registry 
43
interface has only been tested on Linux systems.
44

    
45
.. figure:: images/screenshots/image033.jpg
46
   :align: center
47

    
48
   An example installation of the Register's web interface. Customize the 
49
   displayed and required modules with the Skins Configuration settings.
50
   
51
You can customize which modules (e.g., "Name of Submitter" or "Temporal 
52
Coverage of Data") are displayed and which are required using the Skins 
53
Configuration settings
54

    
55
Installing the Registry
56
~~~~~~~~~~~~~~~~~~~~~~~
57
In order to install and run the Registry, you must have Metacat installed and 
58
Tomcat must be running behind an Apache Web server (see previous sections for 
59
information about installing and configuring Apache to run with Tomcat).
60

    
61
To install and run the Registry:
62

    
63

    
64
1. Install the required system libraries using Ubuntu/Debian (instructions 
65
   Red Hat in sidebar)
66
         
67
  * Install the libraries
68

    
69
    ::
70

    
71
      sudo apt-get install ant libappconfig-perl libxml-libxml-perl \
72
      libxml-libxslt-perl libtemplate-perl libcgi-session-perl \
73
      build-essential libnet-ldap-perl libterm-readkey-perl \
74
      libxml-dom-perl libsoap-lite-perl -y
75

    
76
  * Install two more package using cpan 
77

    
78
    ::
79
    
80
      sudo cpan -i Digest::SHA1
81
      sudo cpan -i Config::Properties
82
      sudo cpan -i Scalar::Util
83
      sudo cpan -i Captcha:reCAPTCHA
84
      sudo cpan -i DateTime
85
      sudo cpan -i Crypt::JWT
86
      sudo cpan -i Crypt::X509
87
          
88
.. sidebar:: Instructions for Red Hat (Alternate Step 2)
89

    
90
  * Install the libraries
91

    
92
    ::
93
    
94
      sudo yum install gcc libxml2-devel libxslt-devel ant -y
95

    
96
  * Install CPAN, which allows us to install the Perl dependencies for the 
97
    registry and account management parts of Metacat. If asked to manually 
98
    configure cpan, type 'no' and CPAN will be setup with its default values.
99

    
100
    ::
101
    
102
      sudo yum install perl-CPAN
103
      sudo cpan
104

    
105
  * You should now see a prompt which looks like:
106

    
107
    ::
108
    
109
      cpan>
110

    
111
  * The rest of the commands assume you're inside of CPAN. Let's get the most 
112
    recent version of the CPAN software. Just press return after any prompts 
113
    you receive during this process.
114
    
115
    ::
116
    
117
      install Bundle::CPAN
118
      reload cpan
119

    
120
  * Install the required modules. Here we're installing an old LibXSLT, as the 
121
    current one requires a newer libxslt than is available on Redhat 4 & 5. 
122
    Again, just answer 'yes' to any questions.
123

    
124
    ::
125

    
126
      install AutoLoader
127
      install CGI
128
      install CGI::SEssion
129
      install LWP::UserAgent
130
      install Net::LDAP
131
      install Template 
132
      install URI
133
      install MSERGEANT/XML-LibXSLT-1.58.tar.gz
134
      install Captcha:reCAPTCHA
135
      install DateTime
136
      install Crypt::JWT
137
      install Crypt::X509
138

    
139

    
140
2. Double-check that Metacat's temporary folder, application.tempDir, is 
141
   writable by the apache user, usually www-data or apache. 
142

    
143
3. Make sure that the following scripts (found in ``<tomcat-home>/webapps/metacat/cgi-bin``) 
144
   are executable: register-dataset.cgi and ldapweb.cgi.
145

    
146
  ::
147
  
148
    sudo chmod +x <tomcat-home>/webapps/metacat/cgi-bin/*.cgi
149

    
150
4. Ensure apache CGI module is enabled
151

    
152
   ::
153
  
154
    sudo a2enmod cgid
155

    
156
5. Restart Apache.
157

    
158
  ::
159
  
160
    sudo /etc/init.d/apache2 restart
161

    
162
6. Visit the resulting URL: 
163
   http://<your_context_url>/cgi-bin/register-dataset.cgi?cfg=default
164
   Where ``<your_context_url>`` is the URL of the server hosting the Metacat 
165
   followed by the name of the WAR file (i.e., the application context) that 
166
   you installed. For instance, the context URL for the KNB Metacat is: 
167
   http://knb.ecoinformatics.org/knb.
168

    
169
If everything worked correctly, the registry home page will open (see figure).
170

    
171
.. figure:: images/screenshots/image035.jpg
172
   :align: center
173

    
174
   An example of the Registry home page (with the default skin).
175
   
176
Customizing the Registry
177
~~~~~~~~~~~~~~~~~~~~~~~~
178
Before using the registry, you may wish to customize the interface using the 
179
Skins Configuration settings. If you are using the default skin, you must 
180
disable the 'show site list' setting before you can submit the form without 
181
errors. You may also wish to remove (or modify) the list of NCEAS-specific 
182
projects that appear in the default registry. To remove these form fields, 
183
open Metacat's administrative interface (http://<your.context.url>/metacat/admin) 
184
and select the Skins Specific Properties Configuration option. On the skins 
185
configuration page, uncheck the boxes beside any form elements that you do not 
186
wish to appear in the registry.
187

    
188
Once you have saved your changes, you must restart Tomcat for them to come 
189
into effect. To restart Tomcat, type: ``sudo /etc/init.d/tomcat7 restart`` or an 
190
equivalent command appropriate to your operating system. 
191

    
192
.. figure:: images/screenshots/image037.jpg
193
   :align: center
194

    
195
   Uncheck the box beside any setting to remove it from the Registry form. In 
196
   the example, the "Show Site List" and "Show Work Group" form fields, 
197
   corresponding to the "Station Name" and "NCEAS Project" drop-down lists in 
198
   the registry form, have been removed.
199
   
200
LDAP account management
201
~~~~~~~~~~~~~~~~~~~~~~~~
202
If you intend to use Metacat's built-in LDAP account management feature, 
203
you will need public and private keys for the reCaptcha widget.
204

    
205
1. Get private and public recaptcha keys from Google using your Google account:
206
https://www.google.com/recaptcha/admin/create
207

    
208
2. Configure Metacat to use those keys in the metacat.properties file:
209

    
210
  ::
211
  
212
	ldap.recaptcha.publickey=<your public key>
213
	ldap.recaptcha.privatekey=<your private key>
214

    
215
3. Restart Tomcat
216

    
217
   
218
Using HTML Forms (the HTTP Interface)
219
-------------------------------------
220
Metacat's HTTP interface supports Get and Post requests and a variety of actions (Table 4.1) that facilitate information retrieval and storage. HTTP requests can be sent from any client application that communicates using the Web's HTTP protocol. 
221

    
222
* Supported Actions (API)
223
* Logging in
224
* Inserting, Updating, and Deleting XML and Data Documents
225
* Searching Metacat
226
* Paged Query Return
227
* Reading Data and Metadata
228

    
229
Supported Actions
230
~~~~~~~~~~~~~~~~~
231
Metacat supports get and post requests as well as actions for writing, querying, 
232
and reading stored XML. In addition, the HTTP interface includes functions for 
233
validating and transforming XML documents (see table). 
234

    
235
Note that if Replication is enabled, Metacat recognizes several additional 
236
actions, included in Table 4.2. For more information about replication, 
237
please see :doc:`replication`.
238

    
239
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
240
| Action                   | Description and Parameters                                                                                                                                                                                                                                         |
241
+==========================+====================================================================================================================================================================================================================================================================+
242
| delete                   | Delete the specified document from the database. For an                                                                                                                                                                                                            |
243
|                          | example, please see Inserting, Updating, and                                                                                                                                                                                                                       |
244
|                          | Deleting XML and Data Documents.                                                                                                                                                                                                                                   |
245
|                          |                                                                                                                                                                                                                                                                    |
246
|                          | ``docid`` - the docid of the document to delete                                                                                                                                                                                                                    |
247
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
248
| export                   | Export a data package in a zip file.                                                                                                                                                                                                                               |
249
|                          |                                                                                                                                                                                                                                                                    |
250
|                          | ``docid`` - the docid of the document to delete                                                                                                                                                                                                                    |
251
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
252
| getaccesscontrol         | Get the access control list (ACL) for the                                                                                                                                                                                                                          |
253
|                          | specified document.                                                                                                                                                                                                                                                |
254
|                          |                                                                                                                                                                                                                                                                    |
255
|                          | ``docid`` - the docid of the document to delete                                                                                                                                                                                                                    |
256
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
257
| getalldocids             | Retrieve a list of all docids registered with the system.                                                                                                                                                                                                          |
258
|                          |                                                                                                                                                                                                                                                                    |
259
|                          | ``scope`` - a string used to match a range of docids in a SQL LIKE statement                                                                                                                                                                                       |
260
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
261
| getdataguide             | Read a data guide for the specified document type                                                                                                                                                                                                                  |
262
| DEPRECATED               |                                                                                                                                                                                                                                                                    |
263
| Use getdtdschema instead | ``doctype`` - the doctype for which to get the data guide                                                                                                                                                                                                          |
264
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
265
| getdoctypes              | Get all doctypes currently available in the Metacat Catalog System. No parameters.                                                                                                                                                                                 |
266
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
267
| getdtdschema             | Read the DTD or XMLSchema file for the specified doctype.                                                                                                                                                                                                          |
268
|                          |                                                                                                                                                                                                                                                                    |
269
|                          | ``doctype`` - the doctype for which DTD or XMLSchema files to read                                                                                                                                                                                                 |
270
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
271
| getlastdocid             | Get the latest docid with revision number used by scope.                                                                                                                                                                                                           |
272
|                          |                                                                                                                                                                                                                                                                    |
273
|                          | ``scope`` - the scope to be queried                                                                                                                                                                                                                                |
274
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
275
| getlog                   | Get the latest docid with revision number used by user.                                                                                                                                                                                                            |
276
|                          |                                                                                                                                                                                                                                                                    |
277
|                          | ``ipaddress`` - the internet protocol address for the event                                                                                                                                                                                                        |
278
|                          | ``principal`` - the principal for the event (a username, etc)                                                                                                                                                                                                      |
279
|                          | ``docid`` - the identifier of the document to which the event applies                                                                                                                                                                                              |
280
|                          | ``event`` - the string code for the event                                                                                                                                                                                                                          |
281
|                          | ``start`` - beginning of date-range for query                                                                                                                                                                                                                      |
282
|                          | ``end`` - end of date-range for query                                                                                                                                                                                                                              |
283
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
284
| getloggedinuserinfo      | Get user info for the currently logged in user. No parameters.                                                                                                                                                                                                     |
285
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
286
| getpricipals             | Get all users and groups in the current authentication schema. No parameters.                                                                                                                                                                                      |
287
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
288
| getrevisionanddoctype    | Return the revision and doctype of a document.                                                                                                                                                                                                                     |
289
|                          | The output is String that looks like "rev;doctype"                                                                                                                                                                                                                 |
290
|                          |                                                                                                                                                                                                                                                                    |
291
|                          | ``docid`` - the docid of the document                                                                                                                                                                                                                              |
292
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
293
| getversion               | Get Metacat version.   Return the current version of Metacat as XML. No parameters.                                                                                                                                                                                |
294
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
295
| insert                   | Insert an XML document into the database. For an example, please see                                                                                                                                                                                               |
296
|                          | Inserting, Updating, and Deleting XML and Data Documents                                                                                                                                                                                                           |
297
|                          |                                                                                                                                                                                                                                                                    |
298
|                          | ``docid`` - the user-defined docid to assign to the new XML document                                                                                                                                                                                               |
299
|                          | ``doctext`` - the text of the XML document to insert                                                                                                                                                                                                               |
300
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
301
| insertmultipart          | Insert an XML document using multipart encoding into the database.                                                                                                                                                                                                 |
302
|                          |                                                                                                                                                                                                                                                                    |
303
|                          | ``docid`` - the user-defined docid to assign to the new XML document                                                                                                                                                                                               |
304
|                          | ``doctext`` - the text of the XML document to insert                                                                                                                                                                                                               |
305
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
306
| isregistered             | Check if an individual document exists in either the xml_documents or xml_revisions tables.                                                                                                                                                                        |
307
|                          | For more information about Metacat's database schema, please see the developer documentation.                                                                                                                                                                      |
308
|                          |                                                                                                                                                                                                                                                                    |
309
|                          | ``docid`` - the docid of the document                                                                                                                                                                                                                              |
310
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
311
| login                    | Log the user in. You must log in using this action before you can perform                                                                                                                                                                                          |
312
|                          | many of the actions. For an example of the login action, see Logging In.                                                                                                                                                                                           |
313
|                          |                                                                                                                                                                                                                                                                    |
314
|                          | ``username`` - the user's login name                                                                                                                                                                                                                               |
315
|                          | ``password`` - the user's password                                                                                                                                                                                                                                 |
316
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
317
| logout                   | Log the current user out and destroy the associated session. No parameters.                                                                                                                                                                                        |
318
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
319
| query                    | Perform a free text query. For an example, please see Searching Metacat.                                                                                                                                                                                           |
320
|                          |                                                                                                                                                                                                                                                                    |
321
|                          | ``returndoctype`` - the doctype to use for your Package View. For more information about packages, see http://knb.ecoinformatics.org/software/metacat/packages.html                                                                                                |
322
|                          | ``qformat`` - the format of the returned result set. Possible values are html or xml or the name of your servlet's Metacat skin.                                                                                                                                   |
323
|                          | ``querytitle`` - OPTIONAL - the title of the query                                                                                                                                                                                                                 |
324
|                          | ``doctype`` - OPTIONAL - if doctype is specified, the search is limited only to the specified doctype(s). (e.g., eml://ecoinformatics.org/eml-2.0.1 and/or eml://ecoinformatics.org/eml-2.0.0) If no doctype element is specified, all document types are returned |
325
|                          | ``returnfield`` - a custom field to be returned by any hit document.                                                                                                                                                                                               |
326
|                          | ``operator`` - the Boolean operator to apply to the query. Possible values are: union or intersect                                                                                                                                                                 |
327
|                          | ``searchmode`` - the type of search to be performed. Possible values are: contains, starts-with, ends-with, equals, isnot-equal, greater-than, less-than, greater-than-equals, less-than-equals.                                                                   |
328
|                          | ``anyfield`` - a free-text search variable. The value placed in this parameter will be searched for in any document in any node.                                                                                                                                   |
329
|                          | ``pagesize`` - the number of search results to display on each search results page (e.g., 10). Used with pagestart. See section 4.3.4 for an example.                                                                                                              |
330
|                          | ``pagestart`` - the displayed search results page (e.g, 1). Used with pagesize. See section 4.3.4 for an example.                                                                                                                                                  |
331
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
332
| read                     | Get a document from the database and return it in the specified format. See Searching Metacat for an example.                                                                                                                                                      |
333
|                          |                                                                                                                                                                                                                                                                    |
334
|                          | ``docid`` - the docid of the document to return                                                                                                                                                                                                                    |
335
|                          | ``qformat`` - the format to return the document in. Possible values are: ``html``, ``xml``,or, if your Metacat uses a skin, the name of the skin.                                                                                                                  |
336
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
337
| readinlinedata           | Read inline data only.                                                                                                                                                                                                                                             |
338
|                          |                                                                                                                                                                                                                                                                    |
339
|                          | ``inlinedataid`` - the id of the inline data to read                                                                                                                                                                                                               |
340
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
341
| setaccess                | Change access permissions for a user on a specified document.                                                                                                                                                                                                      |
342
|                          |                                                                                                                                                                                                                                                                    |
343
|                          | ``docid`` - the docid of the document to be modified.                                                                                                                                                                                                              |
344
|                          | ``principal`` - the user or group whose permissions will be modified                                                                                                                                                                                               |
345
|                          | ``permission`` - the permission  to set (read, write, all)                                                                                                                                                                                                         |
346
|                          | ``permType`` - the type of permission to set (allow, deny)                                                                                                                                                                                                         |
347
|                          | ``permOrder`` - the order in which to apply the permission (allowFirst, denyFirst)                                                                                                                                                                                 |
348
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
349
| spatial_query            | Perform a spatial query. These queries may include any of the queries supported by the                                                                                                                                                                             |
350
|                          | WFS / WMS standards. For more information, see Spatial Queries.                                                                                                                                                                                                    |
351
|                          |                                                                                                                                                                                                                                                                    |
352
|                          | ``xmax`` - max x spatial coordinate                                                                                                                                                                                                                                |
353
|                          | ``ymax`` - max y spatial coordinate                                                                                                                                                                                                                                |
354
|                          | ``xmin`` - min x spatial coordinate                                                                                                                                                                                                                                |
355
|                          | ``ymin`` - min y spatial coordinate                                                                                                                                                                                                                                |
356
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
357
| squery                   | Perform a structured query. For an example, please see Searching Metacat.                                                                                                                                                                                          |
358
|                          |                                                                                                                                                                                                                                                                    |
359
|                          | ``query`` - the text of the pathquery document sent to the server                                                                                                                                                                                                  |
360
|                          | ``qformat`` - the format to return the results in. Possible values are:  ``xml``, or the name of the a skin.                                                                                                                                                       |
361
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
362
| update                   | Overwrite an XML document with a new one and give the new one the same docid but with                                                                                                                                                                              |
363
|                          | the next revision number. For an example, please see Inserting, Updating, and                                                                                                                                                                                      |
364
|                          | Deleting XML and Data Documents.                                                                                                                                                                                                                                   |
365
|                          |                                                                                                                                                                                                                                                                    |
366
|                          | ``docid`` - the docid of the document to update                                                                                                                                                                                                                    |
367
|                          | ``doctext`` - the text with which to update the XML document                                                                                                                                                                                                       |
368
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
369
| upload                   | Upload (insert or update) a data file into Metacat. Data files are stored on Metacat and may be in any                                                                                                                                                             |
370
|                          | format (binary or text), but they are all treated as if they were binary.                                                                                                                                                                                          |
371
|                          |                                                                                                                                                                                                                                                                    |
372
|                          | ``docid`` - the docid of the data file to upload                                                                                                                                                                                                                   |
373
|                          | ``datafile`` - the data file to upload                                                                                                                                                                                                                             |
374
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
375
| validate                 | Validate a specified document against its DTD.                                                                                                                                                                                                                     |
376
|                          |                                                                                                                                                                                                                                                                    |
377
|                          | ``docid`` - the docid of the document to validate                                                                                                                                                                                                                  |
378
|                          | ``valtext`` - the DTD by which to validate this document                                                                                                                                                                                                           |
379
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
380

    
381

    
382
Metacat Replication Parameters
383

    
384
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
385
| Action         | Description and Parameters                                                                                                                                      |
386
+================+=================================================================================================================================================================+
387
| forcereplicate | Force the local server to get the specified document from the remote host.                                                                                      |
388
|                |                                                                                                                                                                 |
389
|                | ``server`` - The server to which this document is being sent                                                                                                    |
390
|                | ``docid`` - The docid of the document to send                                                                                                                   |
391
|                | ``dbaction`` - The action to perform on the document: insert or update (the default)                                                                            |
392
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
393
| getall         | Force the local server to check all known servers for updated documents. No parameters.                                                                         |
394
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
395
| getcatalog     | Send the contents of the xml_catalog table encoded in XML. No parameters.                                                                                       |
396
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
397
| getlock        | Request a lock on the specified document.                                                                                                                       |
398
|                |                                                                                                                                                                 |
399
|                | ``docid`` - the docid of the document                                                                                                                           |
400
|                | ``updaterev`` - the revision number of docid                                                                                                                    |
401
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
402
| gettime        | Return the local time on this server. No parameters.                                                                                                            |
403
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
404
| servercontrol  | Perform the specified replication control on the Replication daemon.                                                                                            |
405
|                |                                                                                                                                                                 |
406
|                | ``add`` - add a new server to the replication list                                                                                                              |
407
|                | ``delete`` - remove a server from the replication list                                                                                                          |
408
|                | ``list`` - list all of the servers currently in the server list                                                                                                 |
409
|                | ``replicate`` - a Boolean flag (1 or 0) which determines if this server should copy files from the newly added server.                                          |
410
|                | ``server`` - the server to add/delete                                                                                                                           |
411
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
412
| read           | Sends docid to the remote host.                                                                                                                                 |
413
|                |                                                                                                                                                                 |
414
|                | ``docid`` - the docid of the document to read                                                                                                                   |
415
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
416
| start          | Start the Replication daemon with a time interval of deltaT.                                                                                                    |
417
|                |                                                                                                                                                                 |
418
|                | ``rate`` - The rate (in seconds) at which you want the replication daemon to check for updated documents. The value cannot be less than 30. The default is 1000 |
419
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
420
| stop           | Stop the Replication daemon. No parameters.                                                                                                                     |
421
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
422
| update         | Send a list of all documents on the local server along with their revision numbers. No parameters.                                                              |
423
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
424

    
425
Logging In
426
~~~~~~~~~~
427
To log in to Metacat, use the ``login`` action.
428

    
429
The following is an example of a Web form (see figure) that logs a user into 
430
Metact. Example HTML code is included below the screenshot.
431

    
432
.. figure:: images/screenshots/image039.jpg
433
   :align: center
434
   
435
   Logging into Metacat using an HTML form.
436

    
437
::
438

    
439
  <html>
440
  <body>
441
  <form name="loginform" method="post"action="http://yourserver.com/yourcontext/servlet/metacat" 
442
  target="_top" onsubmit="return submitform(this);" id="loginform">
443
    <input type="hidden" name="action" value="login"> <input type=
444
    "hidden" name="username" value=""> <input type="hidden" name=
445
    "qformat" value="xml"> <input type="hidden" name=
446
    "enableediting" value="false">
447

    
448
    <table>
449
      <tr valign="middle">
450
        <td align="left" valign="middle" class="text_plain">
451
        username:</td>
452

    
453
        <td width="173" align="left" class="text_plain" style=
454
        "padding-top: 2px; padding-bottom: 2px;"><input name="uid"
455
        type="text" style="width: 140px;" value=""></td>
456
      </tr>
457

    
458
      <tr valign="middle">
459
        <td height="28" align="left" valign="middle" class=
460
        "text_plain">organization:</td>
461

    
462
        <td align="left" class="text_plain" style=
463
        "padding-top: 2px; padding-bottom: 2px;"><select name=
464
        "organization" style="width:140px;">
465
          <option value=""    selected>&#8212; choose one &#8212;</option>
466
          <option value="NCEAS">NCEAS</option>
467
          <option value="LTER">LTER</option>
468
          <option value="UCNRS">UCNRS</option>
469
          <option value="PISCO">PISCO</option>
470
          <option value="OBFS">OBFS</option>
471
          <option value="OSUBS">OSUBS</option>
472
          <option value="SAEON">SAEON</option>
473
          <option value="SANParks">SANParks</option>
474
          <option value="SDSC">SDSC</option>
475
          <option value="KU">KU</option>
476
          <option value="unaffiliated">unaffiliated</option>
477
        </select></td>
478
      </tr>
479

    
480
      <tr valign="middle">
481
        <td width="85" align="left" valign="middle" class=
482
        "text_plain">password:</td>
483

    
484
        <td colspan="2" align="left" class="text_plain" style=
485
        "padding-top: 2px; padding-bottom: 2px;">
486
          <table width="100%" border="0" cellpadding="0"
487
          cellspacing="0">
488
            <tr>
489
              <td width="150" align="left"><input name="password"
490
              type="password" maxlength="50" style="width:140px;"
491
              value=""></td>
492

    
493
              <td align="center" class="buttonBG_login">
494
              <input type="submit" name="loginAction" value="Login"
495
              class="button_login"></td>
496

    
497
              <td align="left">&nbsp;</td>
498
            </tr>
499
          </table>
500
        </td>
501
      </tr>
502
    </table>
503
  </form>
504
  </body>
505
  </html>
506

    
507
Inserting, Updating, and Deleting XML and Data Documents
508
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
509
Adding, editing, and deleting XML documents in Metacat can be accomplished 
510
using the insert, update, and delete actions, respectively. Before you can 
511
insert, delete, or update documents, you must log in to Metacat using the 
512
login action. See Logging in for an example.
513

    
514
``insert``
515
   Insert a new XML or data document into Metacat. You must specify a document ID.
516
   
517
``update``
518
   Update an existing Metacat document. The original document is archived, 
519
   then overwritten.
520

    
521
``delete``
522
   Archive a document and move the pointer in xml_documents to xml_revisions, 
523
   effectively "deleting" the document from public view, but preserving the 
524
   revision for the revision history. No further updates will be allowed for
525
   the Metacat document that was "deleted". All revisions of this identifier are no longer 
526
   public. 
527

    
528
.. warning::
529
   It is not possible to "delete" one revision without "deleting" all 
530
   revisions of a given identifier.
531

    
532
The following is an example of a Web form (see figure) that can perform all 
533
three tasks. Example HTML code is included in the sidebar.
534

    
535
.. figure:: images/screenshots/image041.jpg
536
   :align: center
537
   
538
   An example of a Web form used to insert, delete, or update XML documents in Metacat.
539

    
540
::
541

    
542
  <html>
543
    <head>
544
    <title>MetaCat</title>
545
    </head>
546
    <body class="emlbody">
547
    <b>MetaCat XML Loader</b>
548
    <p>
549
    Upload, Change, or Delete an XML document using this form.
550
    </p>
551
    <form action="http://yourserver.com/yourcontext/servlet/metacat" method="POST">
552
      <strong>1. Choose an action: </strong>
553
      <input type="radio" name="action" value="insert" checked> Insert
554
      <input type="radio" name="action" value="update"> Update
555
      <input type="radio" name="action" value="delete"> Delete
556
      <input type="submit" value="Process Action">
557
      <br />
558
      <strong>2. Provide a Document ID </strong>
559
      <input type="text" name="docid"> (optional for Insert)
560
         <input type="checkbox" name="public" value="yes" checked><strong>Public Document</strong>
561
      <br />
562
      <strong>3. Provide XML text </strong> (not needed for Delete)<br/>
563
      <textarea name="doctext" cols="65" rows="15"></textarea><br/>
564
      <strong>4. Provide DTD text for upload </strong> (optional; not needed for Delete)
565
      <textarea name="dtdtext" cols="65" rows="15"></textarea>
566
    </form>
567
    </body>
568
  </html>
569

    
570
Searching Metacat
571
~~~~~~~~~~~~~~~~~
572
To search Metacat use the ``query`` or ``squery`` actions. 
573

    
574
``query``:   
575
   Perform a free text query. Specify the returndoctype, qformat, returnfield, 
576
   operator, searchmode, anyfield, and (optionally) a querytitle and doctype. 
577

    
578
``squery``:
579
   Perform a structured query by submitting an XML pathquery document to the 
580
   Metacat server.
581
 
582

    
583
When Metacat receives a query via HTTP (screenshot below), the server creates a 
584
"pathquery" document, which is an XML document populated with the specified 
585
search criteria. The pathquery document is then translated into 
586
SQL statements that are executed against the database. Results are translated 
587
into an XML "resultset" document, which can be returned as XML or transformed 
588
into HTML and returned (specify which you would prefer with the returnfield 
589
parameter). You can also opt to submit a pathquery document directly, 
590
using an squery action.
591

    
592
.. figure:: images/screenshots/image043.jpg
593
   :align: center
594
   
595
   Example of a basic search form using a query action. The HTML code used to create the form is displayed below.
596

    
597
::
598

    
599
  <html>
600
  <head>
601
  <title>Search</title>
602
  </head>
603
  <body>
604
  <form method="POST" action="http://panucci.nceas.ucsb.edu/metacat/metacat">
605

    
606
  Search for:
607

    
608
  <input name="action" value="query" type="hidden">
609
  <input name="operator" value="INTERSECT" type="hidden">
610
  <input name="anyfield" type="text" value=" " size="40">
611
  <input name="qformat" value="html" type="hidden">
612
  
613
  <input name="returnfield" value="creator/individualName/surName" type="hidden">
614
  <input name="returnfield" value="creator/individualName/givenName" type="hidden">
615
  <input name="returnfield" value="creator/organizationName" type="hidden">
616
  <input name="returnfield" value="dataset/title" type="hidden">
617
  <input name="returnfield" value="keyword" type="hidden">
618

    
619
  <input name="returndoctype" value="eml://ecoinformatics.org/eml-2.0.1" type="hidden">
620

    
621
  <input value="Start Search" type="submit">
622

    
623
  </form>
624
  </body>
625
  </html>
626
  
627
Metacat's pathquery document can query specific fields of any XML document. 
628
The pathquery can also be used to specify which fields from each hit are 
629
returned and displayed in the search result set.
630

    
631
::
632

    
633
  <pathquery version="1.0">
634
      <meta_file_id>unspecified</meta_file_id>
635
      <querytitle>unspecified</querytitle>
636
      <returnfield>dataset/title</returnfield>
637
      <returnfield>keyword</returnfield>
638
      <returnfield>dataset/creator/individualName/surName</returnfield>
639
      <returndoctype>eml://ecoinformatics.org/eml-2.1.0</returndoctype>      
640
      <returndoctype>eml://ecoinformatics.org/eml-2.0.1</returndoctype>
641
      <returndoctype>eml://ecoinformatics.org/eml-2.0.0</returndoctype>
642
      <querygroup operator="UNION">
643
        <queryterm casesensitive="true" searchmode="contains">
644
          <value>Charismatic megafauna</value>
645
           <pathexpr>dataset/title</pathexpr>
646
         </queryterm>
647
        <queryterm casesensitive="false" searchmode="starts-with">
648
           <value>sea otter</value>
649
           <pathexpr>keyword</pathexpr>
650
        </queryterm>
651
        <queryterm casesensitive="false" searchmode="contains">
652
          <value>Enhydra</value>
653
          <pathexpr>abstract/para</pathexpr>
654
        </queryterm>
655
       </querygroup>
656
   </pathquery>
657
  </pathquery>
658
  
659
Each ``<returnfield>`` parameter specifies a field that the database will 
660
return (in addition to the fields Metacat returns by default) for each search 
661
result. 
662

    
663
The ``<returndoctype>`` field limits the type of returned documents 
664
(eg, eml://ecoinformatics.org/eml-2.0.1 and/or eml://ecoinformatics.org/eml-2.0.0). 
665
If no returndoctype element is specified, all document types are returned. 
666

    
667
A ``<querygroup>`` creates an AND or an OR statement that applies to the 
668
nested ``<queryterm>`` tags. The querygroup operator can be UNION or INTERSECT. 
669
A ``<queryterm>`` defines the actual field (contained in ``<pathexpr>`` tags) 
670
against which the query (contained in the ``<value>`` tags) is being performed. 
671

    
672
The ``<pathexpr>`` can also contain a document type keyword contained in 
673
``<returndoc>`` tags. The specified document type applies only to documents 
674
that are packaged together (e.g., a data set and its corresponding metadata file). 
675
If Metacat identifies the search term in a packaged document, the servlet will 
676
check to see if that document's type matches the specified one. If not, 
677
Metacat will check if one of the other documents in the package matches. If so, 
678
Metacat will return the matching document. For more information about packages, 
679
please see the developer documentation.
680

    
681
After Metacat has processed a Pathquery document, it returns a resultset document.
682

    
683
::
684

    
685
  <resultset>
686
        <query>
687
          <pathquery version="1.0">
688
             <meta_file_id>unspecified</meta_file_id>
689
             <querytitle>unspecified</querytitle>
690
             <returnfield>dataset/title</returnfield>
691
             <returnfield>keyword</returnfield>
692
             <returnfield>dataset/creator/individualName/surName</returnfield>
693
             <returndoctype>eml://ecoinformatics.org/eml-2.1.0</returndoctype>
694
             <returndoctype>eml://ecoinformatics.org/eml-2.0.1</returndoctype>
695
             <returndoctype>eml://ecoinformatics.org/eml-2.0.0</returndoctype>
696
             <querygroup operator="UNION">
697
                  <queryterm casesensitive="true" searchmode="contains">
698
                       <value>Charismatic megafauna</value>
699
                       <pathexpr>dataset/title</pathexpr>
700
                   </queryterm>
701
                   <queryterm casesensitive="false" searchmode="starts-with">
702
                      <value>sea otter</value>
703
                      <pathexpr>keyword</pathexpr>
704
                   </queryterm>
705
                   <queryterm casesensitive="false" searchmode="contains">
706
                      <value>Enhydra</value>
707
                      <pathexpr>abstract/para</pathexpr>
708
                   </queryterm>
709
            </querygroup>
710
          </pathquery>
711
         </query>  
712
       
713
         <document>
714
           <docid>nrs.569.3</docid>
715
           <docname>eml</docname>
716
           <doctype>eml://ecoinformatics.org/eml-2.0.0</doctype>
717
           <createdate>2012-06-06</createdate>
718
           <updatedate>2012-06-06</updatedate>
719
           <param name="dataset/title">Marine Mammal slides</param>
720
           <param name="creator/individualName/surName">Bancroft</param>
721
         </document>
722
 
723
         <document>
724
           <docid>knb-lter-sbc.61.1</docid>
725
           <docname>eml</docname>
726
           <doctype>eml://ecoinformatics.org/eml-2.1.0</doctype>
727
           <createdate>2012-06-06</createdate>
728
           <updatedate>2012-06-06</updatedate>
729
           <param name="dataset/creator/individualName/surName">Nelson</param>
730
           <param name="dataset/creator/individualName/surName">Harrer</param>
731
           <param name="dataset/creator/individualName/surName">Reed</param>
732
           <param name="dataset/title">SBC LTER: Reef: Sightings of Sea Otters (Enhydra lutris) near Santa Barbara and Channel Islands, ongoing since 2007</param>
733
         </document>
734
      .....  
735
  </resultset>
736

    
737
When Metacat returns a resultset document, the servlet always includes the 
738
pathquery used to create it. The pathquery XML is contained in the <query> tag, 
739
the first element in the resultset.
740

    
741
Each XML document returned by the query is represented by a ``<document>`` tag. By 
742
default, Metacat will return the docid, docname, doctype, doctitle, createdate 
743
and updatedate for each search result. If the user specified additional return 
744
fields in the pathquery using ``<returnfield>`` tags (e.g., dataset/title to return 
745
the document title), the additional fields are returned in ``<param>`` tags. 
746

    
747
Metacat can return the XML resultset to your client as either XML or HTML.
748

    
749
Paged Query Returns
750
~~~~~~~~~~~~~~~~~~~
751
Dividing large search result sets over a number of pages speeds load-time and 
752
makes the result sets more readable to users (Figure 4.12). To break your search 
753
results into pages, use the query action's optional pagestart and pagesize 
754
parameters. The pagesize parameter indicates how many results should be 
755
returned for a given page. The pagestart parameter indicates which page you 
756
are currently viewing.
757

    
758
.. figure:: images/screenshots/image045.jpg
759
   :align: center
760
   
761
   An example of paged search results. 
762

    
763
When a paged query is performed, the query's resultset contains four extra 
764
fields: pagestart, pagesize, nextpage, and previouspage (Figure 4.13).  The 
765
nextpage and previouspage fields help Metacat generate navigational links in 
766
the rendered resultset using XSLT to transform the XML to HTML. 
767

    
768
:: 
769

    
770
  <!-- An example of an XML resultset that include support for page breaks. 
771
       The pagestart parameter will always indicate the page you are currently viewing.
772
  -->
773
  <resultset>
774
      <pagestart>1</pagestart>
775
      <pagesize>10</pagesize>
776
      <nextpage>2</nextpage>
777
      <previouspage>0</previouspage>
778
      <query> ...</query>
779
      <document>...</document>
780
      <document>...</document>
781
    </resultset>
782

    
783
The HTML search results displayed in the figure were rendered using Kepler's XSLT, 
784
which can be found in lib/style/skins/kepler. Kepler's XSLT uses the four extra 
785
resultset fields to render the "Next" and "Previous" links.
786

    
787
::
788
  
789
  <a href="metacat?action=query&operator=INTERSECT&enableediting=false&anyfield=actor&qformat=kepler&pagestart=0&pagesize=10">Previous Page</a>
790
  <a href="metacat?action=query&operator=INTERSECT&enableediting=false&anyfield=actor&qformat=kepler&pagestart=2&pagesize=10">Next Page</a>
791
  
792
In the example above, the current page is 1, and the previous page (page 0) and next page (page 2) pages are indicated by the values of the pagestart parameters.
793

    
794
Reading Data and Metadata
795
~~~~~~~~~~~~~~~~~~~~~~~~~
796
To read data or metadata from Metacat, use the ``read`` action. The ``read`` action 
797
takes two parameters: ``docid``, which specifies the document ID of the document 
798
to return, and ``qformat``, which specifies the return format for the document 
799
(``html`` or ``xml`` or the name of a configured style-set, e.g., ``default``). If ``qformat`` 
800
is set to ``xml``, Metacat will return the XML document untransformed. If the 
801
return format is set to ``html``, Metacat will transform the XML document into 
802
HTML using the default XSLT style sheet (specified in the Metacat 
803
configuration). If the name of a style-set is specified, Metacat will use the 
804
XSLT styles specified in the set to transform the XML.
805

    
806
.. figure:: images/screenshots/image047.jpg
807
   :align: center
808
   
809
   The same document displayed using different qformat parameters (from left 
810
   to right: the default style-set, XML, and HTML). 
811

    
812
Note that the ``read`` action can be used to read both data files and metadata files. 
813
To read a data file, you could use the following request::
814

    
815
  http://yourserver.com/yourcontext/metacat?action=read&docid=nceas.55&qformat=default
816

    
817
Where ``nceas.55`` is the docid of the data file stored in the Metacat and 
818
``default`` is the name of the style (you could also use "html" or "xml" or the 
819
name of a customized skin).
820

    
821
::
822
  
823
  <html>
824
  <head>
825
    <title>Read Document</title>
826
  </head>
827
  <body>
828
    <form method="POST" action="http://your.server/your.context/servlet/metacat">
829
      <input name="action" value="read" type="hidden">
830
      <input name="docid" type="text" value="" size="40">
831
      <input name="qformat" value="default" type="hidden">
832
      <input value="Read" type="submit">
833
    </form>
834
  </body>
835
  </html>
836
  
837
Using the EarthGrid API (aka EcoGrid)
838
-------------------------------------
839

    
840
.. Note::
841

    
842
  The EarthGrid/EcoGrid web service API is *deprecated* as of Metacat 2.0.0 and 
843
  will be removed from a future version of Metacat.  Its functionality is being 
844
  replaced by the standardized DataONE REST service interface. The EarthGrid API
845
  will be completely removed by the end of 2013.
846
   
847
The EarthGrid (aka EcoGrid) provides access to disparate data on different 
848
networks (e.g., KNB, GBIF, GEON) and storage systems (e.g., Metacat and SRB), 
849
allowing scientists access to a wide variety of data and analytic resources 
850
(e.g., data, metadata, analytic workflows and processors) networked at different 
851
sites and at different organizations via the internet. 
852

    
853
Because Metacat supports the EarthGrid API (see table), it can query the 
854
distributed EarthGrid, retrieve metadata and data results, and write new and 
855
updated metadata and data back to the grid nodes.
856

    
857
For more information about each EarthGrid service and its WSDL file, navigate 
858
to the "services" page on your Metacat server 
859
(e.g., http://knb.ecoinformatics.org/metacat/services). 
860
Note that the AdminService and Version service that appear on this page are 
861
not part of EarthGrid.
862

    
863
EarthGrid/EcoGrid API Summary
864

    
865
+----------------------------+-----------------------------------------------------------------------------------------------------+
866
| Service                    | Description                                                                                         |
867
+============================+=====================================================================================================+
868
| AuthenticationQueryService | Search for and retrieve protected metadata and data from the EarthGrid as an authenticated user.    |
869
|                            |                                                                                                     |
870
|                            | Methods: ``query``, ``get``                                                                         |
871
+----------------------------+-----------------------------------------------------------------------------------------------------+
872
| AuthenticationService      | Log in and out of the EarthGrid                                                                     |
873
|                            |                                                                                                     |
874
|                            | Methods: ``login``, ``logout``                                                                      |
875
+----------------------------+-----------------------------------------------------------------------------------------------------+
876
| IdentifierService          | List, lookup, validate, and add Life Science Identifiers (LSIDs) to the EarthGrid                   |
877
|                            |                                                                                                     |
878
|                            | Methods: ``isRegistered``, ``addLSID``, ``getNextRevision``, ``getNextObject``, ``getAllIds``       |
879
+----------------------------+-----------------------------------------------------------------------------------------------------+
880
| PutService                 | Write metadata to the EarthGrid                                                                     |
881
|                            |                                                                                                     |
882
|                            | Methods: ``put``                                                                                    |
883
+----------------------------+-----------------------------------------------------------------------------------------------------+
884
| QueryService               | Search for and retrieve metadata from the EarthGrid                                                 |
885
|                            |                                                                                                     |
886
|                            | Methods: ``query``, ``get``                                                                         |
887
+----------------------------+-----------------------------------------------------------------------------------------------------+
888
| RegistryService            | Add, update, remove, and search for registered EarthGrid services.                                  |
889
|                            | Note: The WSDL for this  service is found under http://ecogrid.ecoinformatics.org/registry/services |
890
|                            |                                                                                                     |
891
|                            | Methods: ``add``, ``update``, ``remove``, ``list``, ``query``                                       |
892
+----------------------------+-----------------------------------------------------------------------------------------------------+
893

    
894
Using Morpho
895
------------
896
Morpho is a desktop tool created to facilitate the creation, storage, and 
897
retrieval of metadata. Morpho interfaces with any Metacat server, allowing 
898
users to upload, download, store, query and view relevant metadata and data 
899
using the network. Users can authorize the public or only selected colleagues 
900
to view their data files. 
901

    
902
Morpho is part of the Knowledge Network for Biocomplexity (KNB), a national 
903
network intended to facilitate ecological and environmental research on 
904
biocomplexity. To use Morpho with your Metacat, set the Metacat URL in the 
905
Morpho Preferences to point to your Metacat server.
906

    
907
.. figure:: images/screenshots/image049.png
908
   :align: center
909
   
910
   Set the Metacat URL in the Morpho preferences to point to your Metacat.
911

    
912
For more information about Morpho, please see: http://knb.ecoinformatics.org/
913

    
914
Creating Your Own Client
915
------------------------
916

    
917
.. Note::
918

    
919
  NOTE: The Client API (and underlying servlet implementation) has been 
920
  deprecated as of Metacat 2.0.0. Future development should utilize the DataONE 
921
  REST service methods. The Client API will be completely removed by the end of 2013.
922
  
923
Metacat's client API is available in Java and Perl (the Java interface is 
924
described in this section and further detailed in the appendix). Some of the 
925
API is also available in Python and Ruby. The API allows client applications 
926
to easily authenticate users and perform basic Metacat operations such as 
927
reading metadata and data files; inserting, updating, and deleting files; and 
928
searching for packages based on metadata matches. 
929

    
930
The Client API is defined by the interface edu.ucsb.nceas.metacat.client.Metacat, 
931
and all operations are fully defined in the javadoc_ documentation. To use the 
932
client API, include the ``metacat-client.jar``, ``utilities.jar``, ``commons-io-2.0.jar``, and 
933
``httpclient.jar`` in your classpath. After including these classes, you can 
934
begin using the API methods (see the next table). 
935

    
936
.. _javadoc: http://knb.ecoinformatics.org/software/metacat/dev/api/index.html
937

    
938
The following code block displays a typical session for reading a document 
939
from Metacat using the Java client API.
940

    
941
::
942
  
943
  String metacatUrl = "http://foo.com/context/metacat";
944
  String username = "uid=jones,o=NCEAS,dc=ecoinformatics,dc=org";
945
  String password = "neverHarcodeAPasswordInCode";
946
  try {
947
      Metacat m = MetacatFactory.createMetacatConnection(metacatUrl);
948
      m.login(username, password);
949
      Reader r = m.read("testdocument.1.1");
950
      // Do whatever you want with Reader r
951
  } catch (MetacatAuthException mae) {
952
      handleError("Authorization failed:\n" + mae.getMessage());
953
  } catch (MetacatInaccessibleException mie) {
954
      handleError("Metacat Inaccessible:\n" + mie.getMessage());
955
  } catch (Exception e) {
956
      handleError("General exception:\n" + e.getMessage());
957
  }
958
  
959
  Operations provided by Client API  (Metacat.java class)
960
  
961
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
962
| Method               | Parameters and Throws                                                                                                                                                                                       | Description                                                                                                                               |
963
+======================+=============================================================================================================================================================================================================+===========================================================================================================================================+
964
| delete               | ``public String delete(String docid) throws InsufficientKarmaException, MetacatException, MetacatInaccessibleException;``                                                                                   | Delete an XML document in the repository.                                                                                                 |
965
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
966
| getAllDocids         | ``public Vector getAllDocids(String scope) throws MetacatException;``                                                                                                                                       | Return a list of all docids that match a given scope. If scope is null, return all docids registered in the system.                       |
967
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
968
| getLastDocid         | ``public String getLastDocid(String scope) throws MetacatException;``                                                                                                                                       | Return the highest document ID for a given scope.  Used by clients to determine the next free identifier in a sequence for a given scope. |
969
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
970
| getloggedinuserinfo  | ``public String getloggedinuserinfo() throws MetacatInaccessibleException;``                                                                                                                                | Return the logged in user for this session.                                                                                               |
971
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
972
| getNewestDocRevision | ``public int getNewestDocRevision(String docId) throws MetacatException;``                                                                                                                                  | Return the latest revision of specified the document from Metacat                                                                         |
973
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
974
| getSessonId          | ``public String getSessionId();``                                                                                                                                                                           | Return the session identifier for this session.                                                                                           |
975
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
976
| insert               | ``public String insert(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;``                                   | Insert an XML document into the repository.                                                                                               |
977
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
978
| isRegistered         | ``public boolean isRegistered(String docid) throws MetacatException;``                                                                                                                                      | Return true if given docid is registered; false if not.                                                                                   |
979
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
980
| login                | ``public String login(String username, String password) throws MetacatAuthException, MetacatInaccessibleException;``                                                                                        | Log in to a Metacat server.                                                                                                               |
981
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
982
| logout               | ``public String logout() throws MetacatInaccessibleException, MetacatException;``                                                                                                                           | Log out of a Metacat server.                                                                                                              |
983
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
984
| query                | ``public Reader query(Reader xmlQuery) throws MetacatInaccessibleException, IOException;``                                                                                                                  | Query the Metacat repository and return the result set as a Reader.                                                                       |
985
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
986
| query                | ``public Reader query(Reader xmlQuery, String qformat) throws MetacatInaccessibleException, IOException;``                                                                                                  | Query the Metacat repository with the given metacat-compatible query format and return the result set as a Reader.                        |
987
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
988
| read                 | ``public Reader read(String docid) throws InsufficientKarmaException, MetacatInaccessibleException, DocumentNotFoundException, MetacatException;``                                                          | Read an XML document from the Metacat server.                                                                                             |
989
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
990
| readInlineData       | ``public Reader readInlineData(String inlinedataid) throws InsufficientKarmaException, MetacatInaccessibleException, MetacatException;``                                                                    | Read inline data from the Metacat server session.                                                                                         |
991
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
992
| setAccess            | ``public String setAccess(String _docid, String _principal, String _permission, String _permType, String _permOrder ); throws InsufficientKarmaException, MetacatException, MetacatInaccessibleException;`` | Set permissions for an XML document in the Metacat repository.                                                                            |
993
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
994
| setMetacatUrl        | ``public void setMetacatUrl(String metacatUrl);``                                                                                                                                                           | Set the MetacatUrl to which connections should be made.                                                                                   |
995
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
996
| setSessionId         | ``public void setSessionId(String sessionId);``                                                                                                                                                             | Set the session identifier for this session.                                                                                              |
997
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
998
| update               | ``public String update(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;``                                   | Update an XML document in the repository by providing a new version of the XML document.                                                  |
999
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
1000
| upload               | ``public String upload(String docid, File file) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;``                                                           | Upload a data document into the repository.                                                                                               |
1001
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
1002
| upload               | ``public String publicupload(String docid, String fileName, InputStream fileData, int size) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;``               | Upload a data document into the repository.                                                                                               |
1003
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
1004
  
(24-24/25)