|
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
|
|
|
86
|
|
|
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
|
|
|
137
|
|
|
138
|
|
|
139
|
2. Double-check that Metacat's temporary folder, application.tempDir, is
|
|
140
|
writable by the apache user, usually www-data or apache.
|
|
141
|
|
|
142
|
3. Make sure that the following scripts (found in ``<tomcat-home>/webapps/metacat/cgi-bin``)
|
|
143
|
are executable: register-dataset.cgi and ldapweb.cgi.
|
|
144
|
|
|
145
|
::
|
|
146
|
|
|
147
|
sudo chmod +x <tomcat-home>/webapps/metacat/cgi-bin/*.cgi
|
|
148
|
|
|
149
|
4. Restart Apache.
|
|
150
|
|
|
151
|
::
|
|
152
|
|
|
153
|
sudo /etc/init.d/apache2 restart
|
|
154
|
|
|
155
|
5. Visit the resulting URL:
|
|
156
|
http://<your_context_url>/cgi-bin/register-dataset.cgi?cfg=default
|
|
157
|
Where ``<your_context_url>`` is the URL of the server hosting the Metacat
|
|
158
|
followed by the name of the WAR file (i.e., the application context) that
|
|
159
|
you installed. For instance, the context URL for the KNB Metacat is:
|
|
160
|
http://knb.ecoinformatics.org/knb.
|
|
161
|
|
|
162
|
If everything worked correctly, the registry home page will open (see figure).
|
|
163
|
|
|
164
|
.. figure:: images/screenshots/image035.jpg
|
|
165
|
:align: center
|
|
166
|
|
|
167
|
An example of the Registry home page (with the default skin).
|
|
168
|
|
|
169
|
Customizing the Registry
|
|
170
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
171
|
Before using the registry, you may wish to customize the interface using the
|
|
172
|
Skins Configuration settings. If you are using the default skin, you must
|
|
173
|
disable the 'show site list' setting before you can submit the form without
|
|
174
|
errors. You may also wish to remove (or modify) the list of NCEAS-specific
|
|
175
|
projects that appear in the default registry. To remove these form fields,
|
|
176
|
open Metacat's administrative interface (http://<your.context.url>/metacat/admin)
|
|
177
|
and select the Skins Specific Properties Configuration option. On the skins
|
|
178
|
configuration page, uncheck the boxes beside any form elements that you do not
|
|
179
|
wish to appear in the registry.
|
|
180
|
|
|
181
|
Once you have saved your changes, you must restart Tomcat for them to come
|
|
182
|
into effect. To restart Tomcat, type: ``sudo /etc/init.d/tomcat6 restart`` or an
|
|
183
|
equivalent command appropriate to your operating system.
|
|
184
|
|
|
185
|
.. figure:: images/screenshots/image037.jpg
|
|
186
|
:align: center
|
|
187
|
|
|
188
|
Uncheck the box beside any setting to remove it from the Registry form. In
|
|
189
|
the example, the "Show Site List" and "Show Work Group" form fields,
|
|
190
|
corresponding to the "Station Name" and "NCEAS Project" drop-down lists in
|
|
191
|
the registry form, have been removed.
|
|
192
|
|
|
193
|
LDAP account management
|
|
194
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
195
|
If you intend to use Metacat's built-in LDAP account management feature,
|
|
196
|
you will need public and private keys for the reCaptcha widget.
|
|
197
|
|
|
198
|
1. Get private and public recaptcha keys from Google using your Google account:
|
|
199
|
https://www.google.com/recaptcha/admin/create
|
|
200
|
|
|
201
|
2. Configure Metacat to use those keys in the metacat.properties file:
|
|
202
|
|
|
203
|
::
|
|
204
|
|
|
205
|
ldap.recaptcha.publickey=<your public key>
|
|
206
|
ldap.recaptcha.privatekey=<your private key>
|
|
207
|
|
|
208
|
3. Restart Tomcat
|
|
209
|
|
|
210
|
|
|
211
|
Using HTML Forms (the HTTP Interface)
|
|
212
|
-------------------------------------
|
|
213
|
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.
|
|
214
|
|
|
215
|
* Supported Actions (API)
|
|
216
|
* Logging in
|
|
217
|
* Inserting, Updating, and Deleting XML and Data Documents
|
|
218
|
* Searching Metacat
|
|
219
|
* Paged Query Return
|
|
220
|
* Reading Data and Metadata
|
|
221
|
|
|
222
|
Supported Actions
|
|
223
|
~~~~~~~~~~~~~~~~~
|
|
224
|
Metacat supports get and post requests as well as actions for writing, querying,
|
|
225
|
and reading stored XML. In addition, the HTTP interface includes functions for
|
|
226
|
validating and transforming XML documents (see table).
|
|
227
|
|
|
228
|
Note that if Replication is enabled, Metacat recognizes several additional
|
|
229
|
actions, included in Table 4.2. For more information about replication,
|
|
230
|
please see :doc:`replication`.
|
|
231
|
|
|
232
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
233
|
| Action | Description and Parameters |
|
|
234
|
+==========================+====================================================================================================================================================================================================================================================================+
|
|
235
|
| delete | Delete the specified document from the database. For an |
|
|
236
|
| | example, please see Inserting, Updating, and |
|
|
237
|
| | Deleting XML and Data Documents. |
|
|
238
|
| | |
|
|
239
|
| | ``docid`` - the docid of the document to delete |
|
|
240
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
241
|
| export | Export a data package in a zip file. |
|
|
242
|
| | |
|
|
243
|
| | ``docid`` - the docid of the document to delete |
|
|
244
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
245
|
| getaccesscontrol | Get the access control list (ACL) for the |
|
|
246
|
| | specified document. |
|
|
247
|
| | |
|
|
248
|
| | ``docid`` - the docid of the document to delete |
|
|
249
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
250
|
| getalldocids | Retrieve a list of all docids registered with the system. |
|
|
251
|
| | |
|
|
252
|
| | ``scope`` - a string used to match a range of docids in a SQL LIKE statement |
|
|
253
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
254
|
| getdataguide | Read a data guide for the specified document type |
|
|
255
|
| DEPRECATED | |
|
|
256
|
| Use getdtdschema instead | ``doctype`` - the doctype for which to get the data guide |
|
|
257
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
258
|
| getdoctypes | Get all doctypes currently available in the Metacat Catalog System. No parameters. |
|
|
259
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
260
|
| getdtdschema | Read the DTD or XMLSchema file for the specified doctype. |
|
|
261
|
| | |
|
|
262
|
| | ``doctype`` - the doctype for which DTD or XMLSchema files to read |
|
|
263
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
264
|
| getlastdocid | Get the latest docid with revision number used by scope. |
|
|
265
|
| | |
|
|
266
|
| | ``scope`` - the scope to be queried |
|
|
267
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
268
|
| getlog | Get the latest docid with revision number used by user. |
|
|
269
|
| | |
|
|
270
|
| | ``ipaddress`` - the internet protocol address for the event |
|
|
271
|
| | ``principal`` - the principal for the event (a username, etc) |
|
|
272
|
| | ``docid`` - the identifier of the document to which the event applies |
|
|
273
|
| | ``event`` - the string code for the event |
|
|
274
|
| | ``start`` - beginning of date-range for query |
|
|
275
|
| | ``end`` - end of date-range for query |
|
|
276
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
277
|
| getloggedinuserinfo | Get user info for the currently logged in user. No parameters. |
|
|
278
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
279
|
| getpricipals | Get all users and groups in the current authentication schema. No parameters. |
|
|
280
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
281
|
| getrevisionanddoctype | Return the revision and doctype of a document. |
|
|
282
|
| | The output is String that looks like "rev;doctype" |
|
|
283
|
| | |
|
|
284
|
| | ``docid`` - the docid of the document |
|
|
285
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
286
|
| getversion | Get Metacat version. Return the current version of Metacat as XML. No parameters. |
|
|
287
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
288
|
| insert | Insert an XML document into the database. For an example, please see |
|
|
289
|
| | Inserting, Updating, and Deleting XML and Data Documents |
|
|
290
|
| | |
|
|
291
|
| | ``docid`` - the user-defined docid to assign to the new XML document |
|
|
292
|
| | ``doctext`` - the text of the XML document to insert |
|
|
293
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
294
|
| insertmultipart | Insert an XML document using multipart encoding into the database. |
|
|
295
|
| | |
|
|
296
|
| | ``docid`` - the user-defined docid to assign to the new XML document |
|
|
297
|
| | ``doctext`` - the text of the XML document to insert |
|
|
298
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
299
|
| isregistered | Check if an individual document exists in either the xml_documents or xml_revisions tables. |
|
|
300
|
| | For more information about Metacat's database schema, please see the developer documentation. |
|
|
301
|
| | |
|
|
302
|
| | ``docid`` - the docid of the document |
|
|
303
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
304
|
| login | Log the user in. You must log in using this action before you can perform |
|
|
305
|
| | many of the actions. For an example of the login action, see Logging In. |
|
|
306
|
| | |
|
|
307
|
| | ``username`` - the user's login name |
|
|
308
|
| | ``password`` - the user's password |
|
|
309
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
310
|
| logout | Log the current user out and destroy the associated session. No parameters. |
|
|
311
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
312
|
| query | Perform a free text query. For an example, please see Searching Metacat. |
|
|
313
|
| | |
|
|
314
|
| | ``returndoctype`` - the doctype to use for your Package View. For more information about packages, see http://knb.ecoinformatics.org/software/metacat/packages.html |
|
|
315
|
| | ``qformat`` - the format of the returned result set. Possible values are html or xml or the name of your servlet's Metacat skin. |
|
|
316
|
| | ``querytitle`` - OPTIONAL - the title of the query |
|
|
317
|
| | ``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 |
|
|
318
|
| | ``returnfield`` - a custom field to be returned by any hit document. |
|
|
319
|
| | ``operator`` - the Boolean operator to apply to the query. Possible values are: union or intersect |
|
|
320
|
| | ``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. |
|
|
321
|
| | ``anyfield`` - a free-text search variable. The value placed in this parameter will be searched for in any document in any node. |
|
|
322
|
| | ``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. |
|
|
323
|
| | ``pagestart`` - the displayed search results page (e.g, 1). Used with pagesize. See section 4.3.4 for an example. |
|
|
324
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
325
|
| read | Get a document from the database and return it in the specified format. See Searching Metacat for an example. |
|
|
326
|
| | |
|
|
327
|
| | ``docid`` - the docid of the document to return |
|
|
328
|
| | ``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. |
|
|
329
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
330
|
| readinlinedata | Read inline data only. |
|
|
331
|
| | |
|
|
332
|
| | ``inlinedataid`` - the id of the inline data to read |
|
|
333
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
334
|
| setaccess | Change access permissions for a user on a specified document. |
|
|
335
|
| | |
|
|
336
|
| | ``docid`` - the docid of the document to be modified. |
|
|
337
|
| | ``principal`` - the user or group whose permissions will be modified |
|
|
338
|
| | ``permission`` - the permission to set (read, write, all) |
|
|
339
|
| | ``permType`` - the type of permission to set (allow, deny) |
|
|
340
|
| | ``permOrder`` - the order in which to apply the permission (allowFirst, denyFirst) |
|
|
341
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
342
|
| spatial_query | Perform a spatial query. These queries may include any of the queries supported by the |
|
|
343
|
| | WFS / WMS standards. For more information, see Spatial Queries. |
|
|
344
|
| | |
|
|
345
|
| | ``xmax`` - max x spatial coordinate |
|
|
346
|
| | ``ymax`` - max y spatial coordinate |
|
|
347
|
| | ``xmin`` - min x spatial coordinate |
|
|
348
|
| | ``ymin`` - min y spatial coordinate |
|
|
349
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
350
|
| squery | Perform a structured query. For an example, please see Searching Metacat. |
|
|
351
|
| | |
|
|
352
|
| | ``query`` - the text of the pathquery document sent to the server |
|
|
353
|
| | ``qformat`` - the format to return the results in. Possible values are: ``xml``, or the name of the a skin. |
|
|
354
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
355
|
| update | Overwrite an XML document with a new one and give the new one the same docid but with |
|
|
356
|
| | the next revision number. For an example, please see Inserting, Updating, and |
|
|
357
|
| | Deleting XML and Data Documents. |
|
|
358
|
| | |
|
|
359
|
| | ``docid`` - the docid of the document to update |
|
|
360
|
| | ``doctext`` - the text with which to update the XML document |
|
|
361
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
362
|
| upload | Upload (insert or update) a data file into Metacat. Data files are stored on Metacat and may be in any |
|
|
363
|
| | format (binary or text), but they are all treated as if they were binary. |
|
|
364
|
| | |
|
|
365
|
| | ``docid`` - the docid of the data file to upload |
|
|
366
|
| | ``datafile`` - the data file to upload |
|
|
367
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
368
|
| validate | Validate a specified document against its DTD. |
|
|
369
|
| | |
|
|
370
|
| | ``docid`` - the docid of the document to validate |
|
|
371
|
| | ``valtext`` - the DTD by which to validate this document |
|
|
372
|
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
373
|
|
|
374
|
|
|
375
|
Metacat Replication Parameters
|
|
376
|
|
|
377
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
378
|
| Action | Description and Parameters |
|
|
379
|
+================+=================================================================================================================================================================+
|
|
380
|
| forcereplicate | Force the local server to get the specified document from the remote host. |
|
|
381
|
| | |
|
|
382
|
| | ``server`` - The server to which this document is being sent |
|
|
383
|
| | ``docid`` - The docid of the document to send |
|
|
384
|
| | ``dbaction`` - The action to perform on the document: insert or update (the default) |
|
|
385
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
386
|
| getall | Force the local server to check all known servers for updated documents. No parameters. |
|
|
387
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
388
|
| getcatalog | Send the contents of the xml_catalog table encoded in XML. No parameters. |
|
|
389
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
390
|
| getlock | Request a lock on the specified document. |
|
|
391
|
| | |
|
|
392
|
| | ``docid`` - the docid of the document |
|
|
393
|
| | ``updaterev`` - the revision number of docid |
|
|
394
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
395
|
| gettime | Return the local time on this server. No parameters. |
|
|
396
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
397
|
| servercontrol | Perform the specified replication control on the Replication daemon. |
|
|
398
|
| | |
|
|
399
|
| | ``add`` - add a new server to the replication list |
|
|
400
|
| | ``delete`` - remove a server from the replication list |
|
|
401
|
| | ``list`` - list all of the servers currently in the server list |
|
|
402
|
| | ``replicate`` - a Boolean flag (1 or 0) which determines if this server should copy files from the newly added server. |
|
|
403
|
| | ``server`` - the server to add/delete |
|
|
404
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
405
|
| read | Sends docid to the remote host. |
|
|
406
|
| | |
|
|
407
|
| | ``docid`` - the docid of the document to read |
|
|
408
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
409
|
| start | Start the Replication daemon with a time interval of deltaT. |
|
|
410
|
| | |
|
|
411
|
| | ``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 |
|
|
412
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
413
|
| stop | Stop the Replication daemon. No parameters. |
|
|
414
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
415
|
| update | Send a list of all documents on the local server along with their revision numbers. No parameters. |
|
|
416
|
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
417
|
|
|
418
|
Logging In
|
|
419
|
~~~~~~~~~~
|
|
420
|
To log in to Metacat, use the ``login`` action.
|
|
421
|
|
|
422
|
The following is an example of a Web form (see figure) that logs a user into
|
|
423
|
Metact. Example HTML code is included below the screenshot.
|
|
424
|
|
|
425
|
.. figure:: images/screenshots/image039.jpg
|
|
426
|
:align: center
|
|
427
|
|
|
428
|
Logging into Metacat using an HTML form.
|
|
429
|
|
|
430
|
::
|
|
431
|
|
|
432
|
<html>
|
|
433
|
<body>
|
|
434
|
<form name="loginform" method="post"action="http://yourserver.com/yourcontext/servlet/metacat"
|
|
435
|
target="_top" onsubmit="return submitform(this);" id="loginform">
|
|
436
|
<input type="hidden" name="action" value="login"> <input type=
|
|
437
|
"hidden" name="username" value=""> <input type="hidden" name=
|
|
438
|
"qformat" value="xml"> <input type="hidden" name=
|
|
439
|
"enableediting" value="false">
|
|
440
|
|
|
441
|
<table>
|
|
442
|
<tr valign="middle">
|
|
443
|
<td align="left" valign="middle" class="text_plain">
|
|
444
|
username:</td>
|
|
445
|
|
|
446
|
<td width="173" align="left" class="text_plain" style=
|
|
447
|
"padding-top: 2px; padding-bottom: 2px;"><input name="uid"
|
|
448
|
type="text" style="width: 140px;" value=""></td>
|
|
449
|
</tr>
|
|
450
|
|
|
451
|
<tr valign="middle">
|
|
452
|
<td height="28" align="left" valign="middle" class=
|
|
453
|
"text_plain">organization:</td>
|
|
454
|
|
|
455
|
<td align="left" class="text_plain" style=
|
|
456
|
"padding-top: 2px; padding-bottom: 2px;"><select name=
|
|
457
|
"organization" style="width:140px;">
|
|
458
|
<option value="" selected>— choose one —</option>
|
|
459
|
<option value="NCEAS">NCEAS</option>
|
|
460
|
<option value="LTER">LTER</option>
|
|
461
|
<option value="UCNRS">UCNRS</option>
|
|
462
|
<option value="PISCO">PISCO</option>
|
|
463
|
<option value="OBFS">OBFS</option>
|
|
464
|
<option value="OSUBS">OSUBS</option>
|
|
465
|
<option value="SAEON">SAEON</option>
|
|
466
|
<option value="SANParks">SANParks</option>
|
|
467
|
<option value="SDSC">SDSC</option>
|
|
468
|
<option value="KU">KU</option>
|
|
469
|
<option value="unaffiliated">unaffiliated</option>
|
|
470
|
</select></td>
|
|
471
|
</tr>
|
|
472
|
|
|
473
|
<tr valign="middle">
|
|
474
|
<td width="85" align="left" valign="middle" class=
|
|
475
|
"text_plain">password:</td>
|
|
476
|
|
|
477
|
<td colspan="2" align="left" class="text_plain" style=
|
|
478
|
"padding-top: 2px; padding-bottom: 2px;">
|
|
479
|
<table width="100%" border="0" cellpadding="0"
|
|
480
|
cellspacing="0">
|
|
481
|
<tr>
|
|
482
|
<td width="150" align="left"><input name="password"
|
|
483
|
type="password" maxlength="50" style="width:140px;"
|
|
484
|
value=""></td>
|
|
485
|
|
|
486
|
<td align="center" class="buttonBG_login">
|
|
487
|
<input type="submit" name="loginAction" value="Login"
|
|
488
|
class="button_login"></td>
|
|
489
|
|
|
490
|
<td align="left"> </td>
|
|
491
|
</tr>
|
|
492
|
</table>
|
|
493
|
</td>
|
|
494
|
</tr>
|
|
495
|
</table>
|
|
496
|
</form>
|
|
497
|
</body>
|
|
498
|
</html>
|
|
499
|
|
|
500
|
Inserting, Updating, and Deleting XML and Data Documents
|
|
501
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
502
|
Adding, editing, and deleting XML documents in Metacat can be accomplished
|
|
503
|
using the insert, update, and delete actions, respectively. Before you can
|
|
504
|
insert, delete, or update documents, you must log in to Metacat using the
|
|
505
|
login action. See Logging in for an example.
|
|
506
|
|
|
507
|
``insert``
|
|
508
|
Insert a new XML or data document into Metacat. You must specify a document ID.
|
|
509
|
|
|
510
|
``update``
|
|
511
|
Update an existing Metacat document. The original document is archived,
|
|
512
|
then overwritten.
|
|
513
|
|
|
514
|
``delete``
|
|
515
|
Archive a document and move the pointer in xml_documents to xml_revisions,
|
|
516
|
effectively "deleting" the document from public view, but preserving the
|
|
517
|
revision for the revision history. No further updates will be allowed for
|
|
518
|
the Metacat document that was "deleted". All revisions of this identifier are no longer
|
|
519
|
public.
|
|
520
|
|
|
521
|
.. warning::
|
|
522
|
It is not possible to "delete" one revision without "deleting" all
|
|
523
|
revisions of a given identifier.
|
|
524
|
|
|
525
|
The following is an example of a Web form (see figure) that can perform all
|
|
526
|
three tasks. Example HTML code is included in the sidebar.
|
|
527
|
|
|
528
|
.. figure:: images/screenshots/image041.jpg
|
|
529
|
:align: center
|
|
530
|
|
|
531
|
An example of a Web form used to insert, delete, or update XML documents in Metacat.
|
|
532
|
|
|
533
|
::
|
|
534
|
|
|
535
|
<html>
|
|
536
|
<head>
|
|
537
|
<title>MetaCat</title>
|
|
538
|
</head>
|
|
539
|
<body class="emlbody">
|
|
540
|
<b>MetaCat XML Loader</b>
|
|
541
|
<p>
|
|
542
|
Upload, Change, or Delete an XML document using this form.
|
|
543
|
</p>
|
|
544
|
<form action="http://yourserver.com/yourcontext/servlet/metacat" method="POST">
|
|
545
|
<strong>1. Choose an action: </strong>
|
|
546
|
<input type="radio" name="action" value="insert" checked> Insert
|
|
547
|
<input type="radio" name="action" value="update"> Update
|
|
548
|
<input type="radio" name="action" value="delete"> Delete
|
|
549
|
<input type="submit" value="Process Action">
|
|
550
|
<br />
|
|
551
|
<strong>2. Provide a Document ID </strong>
|
|
552
|
<input type="text" name="docid"> (optional for Insert)
|
|
553
|
<input type="checkbox" name="public" value="yes" checked><strong>Public Document</strong>
|
|
554
|
<br />
|
|
555
|
<strong>3. Provide XML text </strong> (not needed for Delete)<br/>
|
|
556
|
<textarea name="doctext" cols="65" rows="15"></textarea><br/>
|
|
557
|
<strong>4. Provide DTD text for upload </strong> (optional; not needed for Delete)
|
|
558
|
<textarea name="dtdtext" cols="65" rows="15"></textarea>
|
|
559
|
</form>
|
|
560
|
</body>
|
|
561
|
</html>
|
|
562
|
|
|
563
|
Searching Metacat
|
|
564
|
~~~~~~~~~~~~~~~~~
|
|
565
|
To search Metacat use the ``query`` or ``squery`` actions.
|
|
566
|
|
|
567
|
``query``:
|
|
568
|
Perform a free text query. Specify the returndoctype, qformat, returnfield,
|
|
569
|
operator, searchmode, anyfield, and (optionally) a querytitle and doctype.
|
|
570
|
|
|
571
|
``squery``:
|
|
572
|
Perform a structured query by submitting an XML pathquery document to the
|
|
573
|
Metacat server.
|
|
574
|
|
|
575
|
|
|
576
|
When Metacat receives a query via HTTP (screenshot below), the server creates a
|
|
577
|
"pathquery" document, which is an XML document populated with the specified
|
|
578
|
search criteria. The pathquery document is then translated into
|
|
579
|
SQL statements that are executed against the database. Results are translated
|
|
580
|
into an XML "resultset" document, which can be returned as XML or transformed
|
|
581
|
into HTML and returned (specify which you would prefer with the returnfield
|
|
582
|
parameter). You can also opt to submit a pathquery document directly,
|
|
583
|
using an squery action.
|
|
584
|
|
|
585
|
.. figure:: images/screenshots/image043.jpg
|
|
586
|
:align: center
|
|
587
|
|
|
588
|
Example of a basic search form using a query action. The HTML code used to create the form is displayed below.
|
|
589
|
|
|
590
|
::
|
|
591
|
|
|
592
|
<html>
|
|
593
|
<head>
|
|
594
|
<title>Search</title>
|
|
595
|
</head>
|
|
596
|
<body>
|
|
597
|
<form method="POST" action="http://panucci.nceas.ucsb.edu/metacat/metacat">
|
|
598
|
|
|
599
|
Search for:
|
|
600
|
|
|
601
|
<input name="action" value="query" type="hidden">
|
|
602
|
<input name="operator" value="INTERSECT" type="hidden">
|
|
603
|
<input name="anyfield" type="text" value=" " size="40">
|
|
604
|
<input name="qformat" value="html" type="hidden">
|
|
605
|
|
|
606
|
<input name="returnfield" value="creator/individualName/surName" type="hidden">
|
|
607
|
<input name="returnfield" value="creator/individualName/givenName" type="hidden">
|
|
608
|
<input name="returnfield" value="creator/organizationName" type="hidden">
|
|
609
|
<input name="returnfield" value="dataset/title" type="hidden">
|
|
610
|
<input name="returnfield" value="keyword" type="hidden">
|
|
611
|
|
|
612
|
<input name="returndoctype" value="eml://ecoinformatics.org/eml-2.0.1" type="hidden">
|
|
613
|
|
|
614
|
<input value="Start Search" type="submit">
|
|
615
|
|
|
616
|
</form>
|
|
617
|
</body>
|
|
618
|
</html>
|
|
619
|
|
|
620
|
Metacat's pathquery document can query specific fields of any XML document.
|
|
621
|
The pathquery can also be used to specify which fields from each hit are
|
|
622
|
returned and displayed in the search result set.
|
|
623
|
|
|
624
|
::
|
|
625
|
|
|
626
|
<pathquery version="1.0">
|
|
627
|
<meta_file_id>unspecified</meta_file_id>
|
|
628
|
<querytitle>unspecified</querytitle>
|
|
629
|
<returnfield>dataset/title</returnfield>
|
|
630
|
<returnfield>keyword</returnfield>
|
|
631
|
<returnfield>dataset/creator/individualName/surName</returnfield>
|
|
632
|
<returndoctype>eml://ecoinformatics.org/eml-2.1.0</returndoctype>
|
|
633
|
<returndoctype>eml://ecoinformatics.org/eml-2.0.1</returndoctype>
|
|
634
|
<returndoctype>eml://ecoinformatics.org/eml-2.0.0</returndoctype>
|
|
635
|
<querygroup operator="UNION">
|
|
636
|
<queryterm casesensitive="true" searchmode="contains">
|
|
637
|
<value>Charismatic megafauna</value>
|
|
638
|
<pathexpr>dataset/title</pathexpr>
|
|
639
|
</queryterm>
|
|
640
|
<queryterm casesensitive="false" searchmode="starts-with">
|
|
641
|
<value>sea otter</value>
|
|
642
|
<pathexpr>keyword</pathexpr>
|
|
643
|
</queryterm>
|
|
644
|
<queryterm casesensitive="false" searchmode="contains">
|
|
645
|
<value>Enhydra</value>
|
|
646
|
<pathexpr>abstract/para</pathexpr>
|
|
647
|
</queryterm>
|
|
648
|
</querygroup>
|
|
649
|
</pathquery>
|
|
650
|
</pathquery>
|
|
651
|
|
|
652
|
Each ``<returnfield>`` parameter specifies a field that the database will
|
|
653
|
return (in addition to the fields Metacat returns by default) for each search
|
|
654
|
result.
|
|
655
|
|
|
656
|
The ``<returndoctype>`` field limits the type of returned documents
|
|
657
|
(eg, eml://ecoinformatics.org/eml-2.0.1 and/or eml://ecoinformatics.org/eml-2.0.0).
|
|
658
|
If no returndoctype element is specified, all document types are returned.
|
|
659
|
|
|
660
|
A ``<querygroup>`` creates an AND or an OR statement that applies to the
|
|
661
|
nested ``<queryterm>`` tags. The querygroup operator can be UNION or INTERSECT.
|
|
662
|
A ``<queryterm>`` defines the actual field (contained in ``<pathexpr>`` tags)
|
|
663
|
against which the query (contained in the ``<value>`` tags) is being performed.
|
|
664
|
|
|
665
|
The ``<pathexpr>`` can also contain a document type keyword contained in
|
|
666
|
``<returndoc>`` tags. The specified document type applies only to documents
|
|
667
|
that are packaged together (e.g., a data set and its corresponding metadata file).
|
|
668
|
If Metacat identifies the search term in a packaged document, the servlet will
|
|
669
|
check to see if that document's type matches the specified one. If not,
|
|
670
|
Metacat will check if one of the other documents in the package matches. If so,
|
|
671
|
Metacat will return the matching document. For more information about packages,
|
|
672
|
please see the developer documentation.
|
|
673
|
|
|
674
|
After Metacat has processed a Pathquery document, it returns a resultset document.
|
|
675
|
|
|
676
|
::
|
|
677
|
|
|
678
|
<resultset>
|
|
679
|
<query>
|
|
680
|
<pathquery version="1.0">
|
|
681
|
<meta_file_id>unspecified</meta_file_id>
|
|
682
|
<querytitle>unspecified</querytitle>
|
|
683
|
<returnfield>dataset/title</returnfield>
|
|
684
|
<returnfield>keyword</returnfield>
|
|
685
|
<returnfield>dataset/creator/individualName/surName</returnfield>
|
|
686
|
<returndoctype>eml://ecoinformatics.org/eml-2.1.0</returndoctype>
|
|
687
|
<returndoctype>eml://ecoinformatics.org/eml-2.0.1</returndoctype>
|
|
688
|
<returndoctype>eml://ecoinformatics.org/eml-2.0.0</returndoctype>
|
|
689
|
<querygroup operator="UNION">
|
|
690
|
<queryterm casesensitive="true" searchmode="contains">
|
|
691
|
<value>Charismatic megafauna</value>
|
|
692
|
<pathexpr>dataset/title</pathexpr>
|
|
693
|
</queryterm>
|
|
694
|
<queryterm casesensitive="false" searchmode="starts-with">
|
|
695
|
<value>sea otter</value>
|
|
696
|
<pathexpr>keyword</pathexpr>
|
|
697
|
</queryterm>
|
|
698
|
<queryterm casesensitive="false" searchmode="contains">
|
|
699
|
<value>Enhydra</value>
|
|
700
|
<pathexpr>abstract/para</pathexpr>
|
|
701
|
</queryterm>
|
|
702
|
</querygroup>
|
|
703
|
</pathquery>
|
|
704
|
</query>
|
|
705
|
|
|
706
|
<document>
|
|
707
|
<docid>nrs.569.3</docid>
|
|
708
|
<docname>eml</docname>
|
|
709
|
<doctype>eml://ecoinformatics.org/eml-2.0.0</doctype>
|
|
710
|
<createdate>2012-06-06</createdate>
|
|
711
|
<updatedate>2012-06-06</updatedate>
|
|
712
|
<param name="dataset/title">Marine Mammal slides</param>
|
|
713
|
<param name="creator/individualName/surName">Bancroft</param>
|
|
714
|
</document>
|
|
715
|
|
|
716
|
<document>
|
|
717
|
<docid>knb-lter-sbc.61.1</docid>
|
|
718
|
<docname>eml</docname>
|
|
719
|
<doctype>eml://ecoinformatics.org/eml-2.1.0</doctype>
|
|
720
|
<createdate>2012-06-06</createdate>
|
|
721
|
<updatedate>2012-06-06</updatedate>
|
|
722
|
<param name="dataset/creator/individualName/surName">Nelson</param>
|
|
723
|
<param name="dataset/creator/individualName/surName">Harrer</param>
|
|
724
|
<param name="dataset/creator/individualName/surName">Reed</param>
|
|
725
|
<param name="dataset/title">SBC LTER: Reef: Sightings of Sea Otters (Enhydra lutris) near Santa Barbara and Channel Islands, ongoing since 2007</param>
|
|
726
|
</document>
|
|
727
|
.....
|
|
728
|
</resultset>
|
|
729
|
|
|
730
|
When Metacat returns a resultset document, the servlet always includes the
|
|
731
|
pathquery used to create it. The pathquery XML is contained in the <query> tag,
|
|
732
|
the first element in the resultset.
|
|
733
|
|
|
734
|
Each XML document returned by the query is represented by a ``<document>`` tag. By
|
|
735
|
default, Metacat will return the docid, docname, doctype, doctitle, createdate
|
|
736
|
and updatedate for each search result. If the user specified additional return
|
|
737
|
fields in the pathquery using ``<returnfield>`` tags (e.g., dataset/title to return
|
|
738
|
the document title), the additional fields are returned in ``<param>`` tags.
|
|
739
|
|
|
740
|
Metacat can return the XML resultset to your client as either XML or HTML.
|
|
741
|
|
|
742
|
Paged Query Returns
|
|
743
|
~~~~~~~~~~~~~~~~~~~
|
|
744
|
Dividing large search result sets over a number of pages speeds load-time and
|
|
745
|
makes the result sets more readable to users (Figure 4.12). To break your search
|
|
746
|
results into pages, use the query action's optional pagestart and pagesize
|
|
747
|
parameters. The pagesize parameter indicates how many results should be
|
|
748
|
returned for a given page. The pagestart parameter indicates which page you
|
|
749
|
are currently viewing.
|
|
750
|
|
|
751
|
.. figure:: images/screenshots/image045.jpg
|
|
752
|
:align: center
|
|
753
|
|
|
754
|
An example of paged search results.
|
|
755
|
|
|
756
|
When a paged query is performed, the query's resultset contains four extra
|
|
757
|
fields: pagestart, pagesize, nextpage, and previouspage (Figure 4.13). The
|
|
758
|
nextpage and previouspage fields help Metacat generate navigational links in
|
|
759
|
the rendered resultset using XSLT to transform the XML to HTML.
|
|
760
|
|
|
761
|
::
|
|
762
|
|
|
763
|
<!-- An example of an XML resultset that include support for page breaks.
|
|
764
|
The pagestart parameter will always indicate the page you are currently viewing.
|
|
765
|
-->
|
|
766
|
<resultset>
|
|
767
|
<pagestart>1</pagestart>
|
|
768
|
<pagesize>10</pagesize>
|
|
769
|
<nextpage>2</nextpage>
|
|
770
|
<previouspage>0</previouspage>
|
|
771
|
<query> ...</query>
|
|
772
|
<document>...</document>
|
|
773
|
<document>...</document>
|
|
774
|
</resultset>
|
|
775
|
|
|
776
|
The HTML search results displayed in the figure were rendered using Kepler's XSLT,
|
|
777
|
which can be found in lib/style/skins/kepler. Kepler's XSLT uses the four extra
|
|
778
|
resultset fields to render the "Next" and "Previous" links.
|
|
779
|
|
|
780
|
::
|
|
781
|
|
|
782
|
<a href="metacat?action=query&operator=INTERSECT&enableediting=false&anyfield=actor&qformat=kepler&pagestart=0&pagesize=10">Previous Page</a>
|
|
783
|
<a href="metacat?action=query&operator=INTERSECT&enableediting=false&anyfield=actor&qformat=kepler&pagestart=2&pagesize=10">Next Page</a>
|
|
784
|
|
|
785
|
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.
|
|
786
|
|
|
787
|
Reading Data and Metadata
|
|
788
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
789
|
To read data or metadata from Metacat, use the ``read`` action. The ``read`` action
|
|
790
|
takes two parameters: ``docid``, which specifies the document ID of the document
|
|
791
|
to return, and ``qformat``, which specifies the return format for the document
|
|
792
|
(``html`` or ``xml`` or the name of a configured style-set, e.g., ``default``). If ``qformat``
|
|
793
|
is set to ``xml``, Metacat will return the XML document untransformed. If the
|
|
794
|
return format is set to ``html``, Metacat will transform the XML document into
|
|
795
|
HTML using the default XSLT style sheet (specified in the Metacat
|
|
796
|
configuration). If the name of a style-set is specified, Metacat will use the
|
|
797
|
XSLT styles specified in the set to transform the XML.
|
|
798
|
|
|
799
|
.. figure:: images/screenshots/image047.jpg
|
|
800
|
:align: center
|
|
801
|
|
|
802
|
The same document displayed using different qformat parameters (from left
|
|
803
|
to right: the default style-set, XML, and HTML).
|
|
804
|
|
|
805
|
Note that the ``read`` action can be used to read both data files and metadata files.
|
|
806
|
To read a data file, you could use the following request::
|
|
807
|
|
|
808
|
http://yourserver.com/yourcontext/metacat?action=read&docid=nceas.55&qformat=default
|
|
809
|
|
|
810
|
Where ``nceas.55`` is the docid of the data file stored in the Metacat and
|
|
811
|
``default`` is the name of the style (you could also use "html" or "xml" or the
|
|
812
|
name of a customized skin).
|
|
813
|
|
|
814
|
::
|
|
815
|
|
|
816
|
<html>
|
|
817
|
<head>
|
|
818
|
<title>Read Document</title>
|
|
819
|
</head>
|
|
820
|
<body>
|
|
821
|
<form method="POST" action="http://your.server/your.context/servlet/metacat">
|
|
822
|
<input name="action" value="read" type="hidden">
|
|
823
|
<input name="docid" type="text" value="" size="40">
|
|
824
|
<input name="qformat" value="default" type="hidden">
|
|
825
|
<input value="Read" type="submit">
|
|
826
|
</form>
|
|
827
|
</body>
|
|
828
|
</html>
|
|
829
|
|
|
830
|
Using the EarthGrid API (aka EcoGrid)
|
|
831
|
-------------------------------------
|
|
832
|
|
|
833
|
.. Note::
|
|
834
|
|
|
835
|
The EarthGrid/EcoGrid web service API is *deprecated* as of Metacat 2.0.0 and
|
|
836
|
will be removed from a future version of Metacat. Its functionality is being
|
|
837
|
replaced by the standardized DataONE REST service interface. The EarthGrid API
|
|
838
|
will be completely removed by the end of 2013.
|
|
839
|
|
|
840
|
The EarthGrid (aka EcoGrid) provides access to disparate data on different
|
|
841
|
networks (e.g., KNB, GBIF, GEON) and storage systems (e.g., Metacat and SRB),
|
|
842
|
allowing scientists access to a wide variety of data and analytic resources
|
|
843
|
(e.g., data, metadata, analytic workflows and processors) networked at different
|
|
844
|
sites and at different organizations via the internet.
|
|
845
|
|
|
846
|
Because Metacat supports the EarthGrid API (see table), it can query the
|
|
847
|
distributed EarthGrid, retrieve metadata and data results, and write new and
|
|
848
|
updated metadata and data back to the grid nodes.
|
|
849
|
|
|
850
|
For more information about each EarthGrid service and its WSDL file, navigate
|
|
851
|
to the "services" page on your Metacat server
|
|
852
|
(e.g., http://knb.ecoinformatics.org/metacat/services).
|
|
853
|
Note that the AdminService and Version service that appear on this page are
|
|
854
|
not part of EarthGrid.
|
|
855
|
|
|
856
|
EarthGrid/EcoGrid API Summary
|
|
857
|
|
|
858
|
+----------------------------+-----------------------------------------------------------------------------------------------------+
|
|
859
|
| Service | Description |
|
|
860
|
+============================+=====================================================================================================+
|
|
861
|
| AuthenticationQueryService | Search for and retrieve protected metadata and data from the EarthGrid as an authenticated user. |
|
|
862
|
| | |
|
|
863
|
| | Methods: ``query``, ``get`` |
|
|
864
|
+----------------------------+-----------------------------------------------------------------------------------------------------+
|
|
865
|
| AuthenticationService | Log in and out of the EarthGrid |
|
|
866
|
| | |
|
|
867
|
| | Methods: ``login``, ``logout`` |
|
|
868
|
+----------------------------+-----------------------------------------------------------------------------------------------------+
|
|
869
|
| IdentifierService | List, lookup, validate, and add Life Science Identifiers (LSIDs) to the EarthGrid |
|
|
870
|
| | |
|
|
871
|
| | Methods: ``isRegistered``, ``addLSID``, ``getNextRevision``, ``getNextObject``, ``getAllIds`` |
|
|
872
|
+----------------------------+-----------------------------------------------------------------------------------------------------+
|
|
873
|
| PutService | Write metadata to the EarthGrid |
|
|
874
|
| | |
|
|
875
|
| | Methods: ``put`` |
|
|
876
|
+----------------------------+-----------------------------------------------------------------------------------------------------+
|
|
877
|
| QueryService | Search for and retrieve metadata from the EarthGrid |
|
|
878
|
| | |
|
|
879
|
| | Methods: ``query``, ``get`` |
|
|
880
|
+----------------------------+-----------------------------------------------------------------------------------------------------+
|
|
881
|
| RegistryService | Add, update, remove, and search for registered EarthGrid services. |
|
|
882
|
| | Note: The WSDL for this service is found under http://ecogrid.ecoinformatics.org/registry/services |
|
|
883
|
| | |
|
|
884
|
| | Methods: ``add``, ``update``, ``remove``, ``list``, ``query`` |
|
|
885
|
+----------------------------+-----------------------------------------------------------------------------------------------------+
|
|
886
|
|
|
887
|
Using Morpho
|
|
888
|
------------
|
|
889
|
Morpho is a desktop tool created to facilitate the creation, storage, and
|
|
890
|
retrieval of metadata. Morpho interfaces with any Metacat server, allowing
|
|
891
|
users to upload, download, store, query and view relevant metadata and data
|
|
892
|
using the network. Users can authorize the public or only selected colleagues
|
|
893
|
to view their data files.
|
|
894
|
|
|
895
|
Morpho is part of the Knowledge Network for Biocomplexity (KNB), a national
|
|
896
|
network intended to facilitate ecological and environmental research on
|
|
897
|
biocomplexity. To use Morpho with your Metacat, set the Metacat URL in the
|
|
898
|
Morpho Preferences to point to your Metacat server.
|
|
899
|
|
|
900
|
.. figure:: images/screenshots/image049.png
|
|
901
|
:align: center
|
|
902
|
|
|
903
|
Set the Metacat URL in the Morpho preferences to point to your Metacat.
|
|
904
|
|
|
905
|
For more information about Morpho, please see: http://knb.ecoinformatics.org/
|
|
906
|
|
|
907
|
Creating Your Own Client
|
|
908
|
------------------------
|
|
909
|
|
|
910
|
.. Note::
|
|
911
|
|
|
912
|
NOTE: The Client API (and underlying servlet implementation) has been
|
|
913
|
deprecated as of Metacat 2.0.0. Future development should utilize the DataONE
|
|
914
|
REST service methods. The Client API will be completely removed by the end of 2013.
|
|
915
|
|
|
916
|
Metacat's client API is available in Java and Perl (the Java interface is
|
|
917
|
described in this section and further detailed in the appendix). Some of the
|
|
918
|
API is also available in Python and Ruby. The API allows client applications
|
|
919
|
to easily authenticate users and perform basic Metacat operations such as
|
|
920
|
reading metadata and data files; inserting, updating, and deleting files; and
|
|
921
|
searching for packages based on metadata matches.
|
|
922
|
|
|
923
|
The Client API is defined by the interface edu.ucsb.nceas.metacat.client.Metacat,
|
|
924
|
and all operations are fully defined in the javadoc_ documentation. To use the
|
|
925
|
client API, include the ``metacat-client.jar``, ``utilities.jar``, ``commons-io-2.0.jar``, and
|
|
926
|
``httpclient.jar`` in your classpath. After including these classes, you can
|
|
927
|
begin using the API methods (see the next table).
|
|
928
|
|
|
929
|
.. _javadoc: http://knb.ecoinformatics.org/software/metacat/dev/api/index.html
|
|
930
|
|
|
931
|
The following code block displays a typical session for reading a document
|
|
932
|
from Metacat using the Java client API.
|
|
933
|
|
|
934
|
::
|
|
935
|
|
|
936
|
String metacatUrl = "http://foo.com/context/metacat";
|
|
937
|
String username = "uid=jones,o=NCEAS,dc=ecoinformatics,dc=org";
|
|
938
|
String password = "neverHarcodeAPasswordInCode";
|
|
939
|
try {
|
|
940
|
Metacat m = MetacatFactory.createMetacatConnection(metacatUrl);
|
|
941
|
m.login(username, password);
|
|
942
|
Reader r = m.read("testdocument.1.1");
|
|
943
|
// Do whatever you want with Reader r
|
|
944
|
} catch (MetacatAuthException mae) {
|
|
945
|
handleError("Authorization failed:\n" + mae.getMessage());
|
|
946
|
} catch (MetacatInaccessibleException mie) {
|
|
947
|
handleError("Metacat Inaccessible:\n" + mie.getMessage());
|
|
948
|
} catch (Exception e) {
|
|
949
|
handleError("General exception:\n" + e.getMessage());
|
|
950
|
}
|
|
951
|
|
|
952
|
Operations provided by Client API (Metacat.java class)
|
|
953
|
|
|
954
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
955
|
| Method | Parameters and Throws | Description |
|
|
956
|
+======================+=============================================================================================================================================================================================================+===========================================================================================================================================+
|
|
957
|
| delete | ``public String delete(String docid) throws InsufficientKarmaException, MetacatException, MetacatInaccessibleException;`` | Delete an XML document in the repository. |
|
|
958
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
959
|
| 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. |
|
|
960
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
961
|
| 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. |
|
|
962
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
963
|
| getloggedinuserinfo | ``public String getloggedinuserinfo() throws MetacatInaccessibleException;`` | Return the logged in user for this session. |
|
|
964
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
965
|
| getNewestDocRevision | ``public int getNewestDocRevision(String docId) throws MetacatException;`` | Return the latest revision of specified the document from Metacat |
|
|
966
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
967
|
| getSessonId | ``public String getSessionId();`` | Return the session identifier for this session. |
|
|
968
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
969
|
| insert | ``public String insert(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Insert an XML document into the repository. |
|
|
970
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
971
|
| isRegistered | ``public boolean isRegistered(String docid) throws MetacatException;`` | Return true if given docid is registered; false if not. |
|
|
972
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
973
|
| login | ``public String login(String username, String password) throws MetacatAuthException, MetacatInaccessibleException;`` | Log in to a Metacat server. |
|
|
974
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
975
|
| logout | ``public String logout() throws MetacatInaccessibleException, MetacatException;`` | Log out of a Metacat server. |
|
|
976
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
977
|
| query | ``public Reader query(Reader xmlQuery) throws MetacatInaccessibleException, IOException;`` | Query the Metacat repository and return the result set as a Reader. |
|
|
978
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
979
|
| 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. |
|
|
980
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
981
|
| read | ``public Reader read(String docid) throws InsufficientKarmaException, MetacatInaccessibleException, DocumentNotFoundException, MetacatException;`` | Read an XML document from the Metacat server. |
|
|
982
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
983
|
| readInlineData | ``public Reader readInlineData(String inlinedataid) throws InsufficientKarmaException, MetacatInaccessibleException, MetacatException;`` | Read inline data from the Metacat server session. |
|
|
984
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
985
|
| 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. |
|
|
986
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
987
|
| setMetacatUrl | ``public void setMetacatUrl(String metacatUrl);`` | Set the MetacatUrl to which connections should be made. |
|
|
988
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
989
|
| setSessionId | ``public void setSessionId(String sessionId);`` | Set the session identifier for this session. |
|
|
990
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
991
|
| 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. |
|
|
992
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
993
|
| upload | ``public String upload(String docid, File file) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Upload a data document into the repository. |
|
|
994
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
995
|
| upload | ``public String publicupload(String docid, String fileName, InputStream fileData, int size) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Upload a data document into the repository. |
|
|
996
|
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
|
|
997
|
|