<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>7. Accessing and Submitting Metadata and Data — Metacat 2.8.1 documentation</title>
<link rel="stylesheet" href="_static/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="_static/font-awesome/css/font-awesome.min.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/metacatui.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.8.1',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Metacat 2.8.1 documentation" href="index.html" />
<link rel="prev" title="6. DataONE Member Node Support" href="dataone.html" />
<link rel="next" title="8. Metacat Indexing" href="query-index.html" />
</head>
<body>
<div id="metacatDocs">
<div class="banner">
<a href="index.html"><img class="logo" src="_static/metacat-logo-white.png" /></a>
<a href="index.html"><h1 class="title">Metacat: Metadata and Data Management Server</h1></a>
<img class="logo-right" src="_static/nceas-logo-white.png" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right">
<span id="searchbox" style="display: none;">
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" class="icon-search"/>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</span>
</li>
<script type="text/javascript">$('#searchbox').show(0);</script>
<li class="right">
<a href="genindex.html" title="General Index"
accesskey="I">index</a>
</li>
<li class="right">
<a href="query-index.html" title="8. Metacat Indexing"
accesskey="N">next</a>
</li>
<li class="right">
<a href="dataone.html" title="6. DataONE Member Node Support"
accesskey="P">previous</a>
</li>
<li class="breadcrumb first"><a href="index.html">Metacat 2.8.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="accessing-and-submitting-metadata-and-data">
<h1><a class="toc-backref" href="#id10">7. Accessing and Submitting Metadata and Data</a><a class="headerlink" href="#accessing-and-submitting-metadata-and-data" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#accessing-and-submitting-metadata-and-data" id="id10">Accessing and Submitting Metadata and Data</a><ul>
<li><a class="reference internal" href="#a-brief-note-about-how-information-is-stored" id="id11">A Brief Note about How Information is Stored</a></li>
<li><a class="reference internal" href="#using-the-registry" id="id12">Using the Registry</a><ul>
<li><a class="reference internal" href="#installing-the-registry" id="id13">Installing the Registry</a></li>
<li><a class="reference internal" href="#customizing-the-registry" id="id14">Customizing the Registry</a></li>
<li><a class="reference internal" href="#ldap-account-management" id="id15">LDAP account management</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-html-forms-the-http-interface" id="id16">Using HTML Forms (the HTTP Interface)</a><ul>
<li><a class="reference internal" href="#supported-actions" id="id17">Supported Actions</a></li>
<li><a class="reference internal" href="#logging-in" id="id18">Logging In</a></li>
<li><a class="reference internal" href="#inserting-updating-and-deleting-xml-and-data-documents" id="id19">Inserting, Updating, and Deleting XML and Data Documents</a></li>
<li><a class="reference internal" href="#searching-metacat" id="id20">Searching Metacat</a></li>
<li><a class="reference internal" href="#paged-query-returns" id="id21">Paged Query Returns</a></li>
<li><a class="reference internal" href="#reading-data-and-metadata" id="id22">Reading Data and Metadata</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-the-earthgrid-api-aka-ecogrid" id="id23">Using the EarthGrid API (aka EcoGrid)</a></li>
<li><a class="reference internal" href="#using-morpho" id="id24">Using Morpho</a></li>
<li><a class="reference internal" href="#creating-your-own-client" id="id25">Creating Your Own Client</a></li>
</ul>
</li>
</ul>
</div>
<p>The Metacat repository can be accessed and updated using a number of tools,
including:</p>
<ul class="simple">
<li>the Registry, Metacat’s optional Web interface</li>
<li>user-created HTML forms</li>
<li>Metacat’s EarthGrid API</li>
<li>existing clients, such as KNB’s Morpho application, designed to help
scientists create, edit, and manage metadata</li>
<li>user-created desktop clients that take advantage of Metacat’s Java API.</li>
</ul>
<p>In this section, we will look at how to take advantage of these tools to
customize Metacat for your user-base.</p>
<div class="section" id="a-brief-note-about-how-information-is-stored">
<h2><a class="toc-backref" href="#id11">7.1. A Brief Note about How Information is Stored</a><a class="headerlink" href="#a-brief-note-about-how-information-is-stored" title="Permalink to this headline">¶</a></h2>
<p>Metacat stores XML files as a hierarchy of nodes, where each node is stored as
records in database tables. Because many XML data schemas are broken up into
multiple DTDs requiring multiple XML files that are related but stored
separately in the system, the system uses “packages” to link related but
separate documents. Packaged documents contain information that shows how they
are related to eachother, essentially stating that file A has a relationship
to file B, etc. A package file also allows users to link metadata files to the
data files they describe. For more information about the structure of data
packages and how XML documents and data are stored in Metacat, please see the
developer’s documentation.</p>
</div>
<div class="section" id="using-the-registry">
<h2><a class="toc-backref" href="#id12">7.2. Using the Registry</a><a class="headerlink" href="#using-the-registry" title="Permalink to this headline">¶</a></h2>
<p>Metacat’s optional Registry provides a simple Web-based interface for creating,
editing, and submitting metadata to the Metacat repository (screenshot below). The
interface includes help documentation, and can be customized using Metacat’s
configuration settings. The Registry also includes an administrative interface
for managing LDAP user accounts, which is useful if you are using LDAP as your
Metacat authentication system. Note that you must be running your own LDAP
server if you wish to use the LDAP Web interface. If you do not have your own
LDAP server, you can create and manage new accounts on the KNB website
(<a class="reference external" href="http://knb.ecoinformatics.org/">http://knb.ecoinformatics.org/</a>). Please note that at this time, the Registry
interface has only been tested on Linux systems.</p>
<div class="figure align-center" id="id1">
<img alt="_images/image033.jpg" src="_images/image033.jpg" />
<p class="caption"><span class="caption-text">An example installation of the Register’s web interface. Customize the
displayed and required modules with the Skins Configuration settings.</span></p>
</div>
<p>You can customize which modules (e.g., “Name of Submitter” or “Temporal
Coverage of Data”) are displayed and which are required using the Skins
Configuration settings</p>
<div class="section" id="installing-the-registry">
<h3><a class="toc-backref" href="#id13">7.2.1. Installing the Registry</a><a class="headerlink" href="#installing-the-registry" title="Permalink to this headline">¶</a></h3>
<p>In order to install and run the Registry, you must have Metacat installed and
Tomcat must be running behind an Apache Web server (see previous sections for
information about installing and configuring Apache to run with Tomcat).</p>
<p>To install and run the Registry:</p>
<ol class="arabic simple">
<li>Install the required system libraries using Ubuntu/Debian (instructions
Red Hat in sidebar)</li>
</ol>
<blockquote>
<div><ul>
<li><p class="first">Install the libraries</p>
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install ant libappconfig-perl libxml-libxml-perl \
libxml-libxslt-perl libtemplate-perl libcgi-session-perl \
build-essential libnet-ldap-perl libterm-readkey-perl \
libxml-dom-perl libsoap-lite-perl -y
</pre></div>
</div>
</li>
<li><p class="first">Install two more package using cpan</p>
<div class="highlight-python"><div class="highlight"><pre>sudo cpan -i Digest::SHA1
sudo cpan -i Config::Properties
sudo cpan -i Scalar::Util
sudo cpan -i Captcha:reCAPTCHA
sudo cpan -i DateTime
sudo cpan -i Crypt::JWT
sudo cpan -i Crypt::X509
</pre></div>
</div>
</li>
</ul>
</div></blockquote>
<div class="sidebar">
<p class="first sidebar-title">Instructions for Red Hat (Alternate Step 2)</p>
<ul class="last">
<li><p class="first">Install the libraries</p>
<div class="highlight-python"><div class="highlight"><pre>sudo yum install gcc libxml2-devel libxslt-devel ant -y
</pre></div>
</div>
</li>
<li><p class="first">Install CPAN, which allows us to install the Perl dependencies for the
registry and account management parts of Metacat. If asked to manually
configure cpan, type ‘no’ and CPAN will be setup with its default values.</p>
<div class="highlight-python"><div class="highlight"><pre>sudo yum install perl-CPAN
sudo cpan
</pre></div>
</div>
</li>
<li><p class="first">You should now see a prompt which looks like:</p>
<div class="highlight-python"><div class="highlight"><pre>cpan>
</pre></div>
</div>
</li>
<li><p class="first">The rest of the commands assume you’re inside of CPAN. Let’s get the most
recent version of the CPAN software. Just press return after any prompts
you receive during this process.</p>
<div class="highlight-python"><div class="highlight"><pre>install Bundle::CPAN
reload cpan
</pre></div>
</div>
</li>
<li><p class="first">Install the required modules. Here we’re installing an old LibXSLT, as the
current one requires a newer libxslt than is available on Redhat 4 & 5.
Again, just answer ‘yes’ to any questions.</p>
<div class="highlight-python"><div class="highlight"><pre>install AutoLoader
install CGI
install CGI::SEssion
install LWP::UserAgent
install Net::LDAP
install Template
install URI
install MSERGEANT/XML-LibXSLT-1.58.tar.gz
install Captcha:reCAPTCHA
install DateTime
install Crypt::JWT
install Crypt::X509
</pre></div>
</div>
</li>
</ul>
</div>
<ol class="arabic simple" start="2">
<li>Double-check that Metacat’s temporary folder, application.tempDir, is
writable by the apache user, usually www-data or apache.</li>
<li>Make sure that the following scripts (found in <code class="docutils literal"><span class="pre"><tomcat-home>/webapps/metacat/cgi-bin</span></code>)
are executable: register-dataset.cgi and ldapweb.cgi.</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo chmod +x <tomcat-home>/webapps/metacat/cgi-bin/*.cgi
</pre></div>
</div>
</div></blockquote>
<ol class="arabic" start="4">
<li><p class="first">Ensure apache CGI module is enabled</p>
<div class="highlight-python"><div class="highlight"><pre>sudo a2enmod cgid
</pre></div>
</div>
</li>
<li><p class="first">Restart Apache.</p>
</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>sudo /etc/init.d/apache2 restart
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="6">
<li>Visit the resulting URL:
<a class="reference external" href="http:/">http:/</a>/<your_context_url>/cgi-bin/register-dataset.cgi?cfg=default
Where <code class="docutils literal"><span class="pre"><your_context_url></span></code> is the URL of the server hosting the Metacat
followed by the name of the WAR file (i.e., the application context) that
you installed. For instance, the context URL for the KNB Metacat is:
<a class="reference external" href="http://knb.ecoinformatics.org/knb">http://knb.ecoinformatics.org/knb</a>.</li>
</ol>
<p>If everything worked correctly, the registry home page will open (see figure).</p>
<div class="figure align-center" id="id2">
<img alt="_images/image035.jpg" src="_images/image035.jpg" />
<p class="caption"><span class="caption-text">An example of the Registry home page (with the default skin).</span></p>
</div>
</div>
<div class="section" id="customizing-the-registry">
<h3><a class="toc-backref" href="#id14">7.2.2. Customizing the Registry</a><a class="headerlink" href="#customizing-the-registry" title="Permalink to this headline">¶</a></h3>
<p>Before using the registry, you may wish to customize the interface using the
Skins Configuration settings. If you are using the default skin, you must
disable the ‘show site list’ setting before you can submit the form without
errors. You may also wish to remove (or modify) the list of NCEAS-specific
projects that appear in the default registry. To remove these form fields,
open Metacat’s administrative interface (<a class="reference external" href="http:/">http:/</a>/<your.context.url>/metacat/admin)
and select the Skins Specific Properties Configuration option. On the skins
configuration page, uncheck the boxes beside any form elements that you do not
wish to appear in the registry.</p>
<p>Once you have saved your changes, you must restart Tomcat for them to come
into effect. To restart Tomcat, type: <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">/etc/init.d/tomcat7</span> <span class="pre">restart</span></code> or an
equivalent command appropriate to your operating system.</p>
<div class="figure align-center" id="id3">
<img alt="_images/image037.jpg" src="_images/image037.jpg" />
<p class="caption"><span class="caption-text">Uncheck the box beside any setting to remove it from the Registry form. In
the example, the “Show Site List” and “Show Work Group” form fields,
corresponding to the “Station Name” and “NCEAS Project” drop-down lists in
the registry form, have been removed.</span></p>
</div>
</div>
<div class="section" id="ldap-account-management">
<h3><a class="toc-backref" href="#id15">7.2.3. LDAP account management</a><a class="headerlink" href="#ldap-account-management" title="Permalink to this headline">¶</a></h3>
<p>If you intend to use Metacat’s built-in LDAP account management feature,
you will need public and private keys for the reCaptcha widget.</p>
<p>1. Get private and public recaptcha keys from Google using your Google account:
<a class="reference external" href="https://www.google.com/recaptcha/admin/create">https://www.google.com/recaptcha/admin/create</a></p>
<ol class="arabic simple" start="2">
<li>Configure Metacat to use those keys in the metacat.properties file:</li>
</ol>
<blockquote>
<div><div class="highlight-python"><div class="highlight"><pre>ldap.recaptcha.publickey=<your public key>
ldap.recaptcha.privatekey=<your private key>
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="3">
<li>Restart Tomcat</li>
</ol>
</div>
</div>
<div class="section" id="using-html-forms-the-http-interface">
<h2><a class="toc-backref" href="#id16">7.3. Using HTML Forms (the HTTP Interface)</a><a class="headerlink" href="#using-html-forms-the-http-interface" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<ul class="simple">
<li>Supported Actions (API)</li>
<li>Logging in</li>
<li>Inserting, Updating, and Deleting XML and Data Documents</li>
<li>Searching Metacat</li>
<li>Paged Query Return</li>
<li>Reading Data and Metadata</li>
</ul>
<div class="section" id="supported-actions">
<h3><a class="toc-backref" href="#id17">7.3.1. Supported Actions</a><a class="headerlink" href="#supported-actions" title="Permalink to this headline">¶</a></h3>
<p>Metacat supports get and post requests as well as actions for writing, querying,
and reading stored XML. In addition, the HTTP interface includes functions for
validating and transforming XML documents (see table).</p>
<p>Note that if Replication is enabled, Metacat recognizes several additional
actions, included in Table 4.2. For more information about replication,
please see <a class="reference internal" href="replication.html"><em>Replication</em></a>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="9%" />
<col width="91%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Action</th>
<th class="head">Description and Parameters</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>delete</td>
<td><p class="first">Delete the specified document from the database. For an
example, please see Inserting, Updating, and
Deleting XML and Data Documents.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document to delete</p>
</td>
</tr>
<tr class="row-odd"><td>export</td>
<td><p class="first">Export a data package in a zip file.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document to delete</p>
</td>
</tr>
<tr class="row-even"><td>getaccesscontrol</td>
<td><p class="first">Get the access control list (ACL) for the
specified document.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document to delete</p>
</td>
</tr>
<tr class="row-odd"><td>getalldocids</td>
<td><p class="first">Retrieve a list of all docids registered with the system.</p>
<p class="last"><code class="docutils literal"><span class="pre">scope</span></code> - a string used to match a range of docids in a SQL LIKE statement</p>
</td>
</tr>
<tr class="row-even"><td>getdataguide
DEPRECATED
Use getdtdschema instead</td>
<td><p class="first">Read a data guide for the specified document type</p>
<p class="last"><code class="docutils literal"><span class="pre">doctype</span></code> - the doctype for which to get the data guide</p>
</td>
</tr>
<tr class="row-odd"><td>getdoctypes</td>
<td>Get all doctypes currently available in the Metacat Catalog System. No parameters.</td>
</tr>
<tr class="row-even"><td>getdtdschema</td>
<td><p class="first">Read the DTD or XMLSchema file for the specified doctype.</p>
<p class="last"><code class="docutils literal"><span class="pre">doctype</span></code> - the doctype for which DTD or XMLSchema files to read</p>
</td>
</tr>
<tr class="row-odd"><td>getlastdocid</td>
<td><p class="first">Get the latest docid with revision number used by scope.</p>
<p class="last"><code class="docutils literal"><span class="pre">scope</span></code> - the scope to be queried</p>
</td>
</tr>
<tr class="row-even"><td>getlog</td>
<td><p class="first">Get the latest docid with revision number used by user.</p>
<p class="last"><code class="docutils literal"><span class="pre">ipaddress</span></code> - the internet protocol address for the event
<code class="docutils literal"><span class="pre">principal</span></code> - the principal for the event (a username, etc)
<code class="docutils literal"><span class="pre">docid</span></code> - the identifier of the document to which the event applies
<code class="docutils literal"><span class="pre">event</span></code> - the string code for the event
<code class="docutils literal"><span class="pre">start</span></code> - beginning of date-range for query
<code class="docutils literal"><span class="pre">end</span></code> - end of date-range for query</p>
</td>
</tr>
<tr class="row-odd"><td>getloggedinuserinfo</td>
<td>Get user info for the currently logged in user. No parameters.</td>
</tr>
<tr class="row-even"><td>getpricipals</td>
<td>Get all users and groups in the current authentication schema. No parameters.</td>
</tr>
<tr class="row-odd"><td>getrevisionanddoctype</td>
<td><p class="first">Return the revision and doctype of a document.
The output is String that looks like “rev;doctype”</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document</p>
</td>
</tr>
<tr class="row-even"><td>getversion</td>
<td>Get Metacat version. Return the current version of Metacat as XML. No parameters.</td>
</tr>
<tr class="row-odd"><td>insert</td>
<td><p class="first">Insert an XML document into the database. For an example, please see
Inserting, Updating, and Deleting XML and Data Documents</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the user-defined docid to assign to the new XML document
<code class="docutils literal"><span class="pre">doctext</span></code> - the text of the XML document to insert</p>
</td>
</tr>
<tr class="row-even"><td>insertmultipart</td>
<td><p class="first">Insert an XML document using multipart encoding into the database.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the user-defined docid to assign to the new XML document
<code class="docutils literal"><span class="pre">doctext</span></code> - the text of the XML document to insert</p>
</td>
</tr>
<tr class="row-odd"><td>isregistered</td>
<td><p class="first">Check if an individual document exists in either the xml_documents or xml_revisions tables.
For more information about Metacat’s database schema, please see the developer documentation.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document</p>
</td>
</tr>
<tr class="row-even"><td>login</td>
<td><p class="first">Log the user in. You must log in using this action before you can perform
many of the actions. For an example of the login action, see Logging In.</p>
<p class="last"><code class="docutils literal"><span class="pre">username</span></code> - the user’s login name
<code class="docutils literal"><span class="pre">password</span></code> - the user’s password</p>
</td>
</tr>
<tr class="row-odd"><td>logout</td>
<td>Log the current user out and destroy the associated session. No parameters.</td>
</tr>
<tr class="row-even"><td>query</td>
<td><p class="first">Perform a free text query. For an example, please see Searching Metacat.</p>
<p class="last"><code class="docutils literal"><span class="pre">returndoctype</span></code> - the doctype to use for your Package View. For more information about packages, see <a class="reference external" href="http://knb.ecoinformatics.org/software/metacat/packages.html">http://knb.ecoinformatics.org/software/metacat/packages.html</a>
<code class="docutils literal"><span class="pre">qformat</span></code> - the format of the returned result set. Possible values are html or xml or the name of your servlet’s Metacat skin.
<code class="docutils literal"><span class="pre">querytitle</span></code> - OPTIONAL - the title of the query
<code class="docutils literal"><span class="pre">doctype</span></code> - 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
<code class="docutils literal"><span class="pre">returnfield</span></code> - a custom field to be returned by any hit document.
<code class="docutils literal"><span class="pre">operator</span></code> - the Boolean operator to apply to the query. Possible values are: union or intersect
<code class="docutils literal"><span class="pre">searchmode</span></code> - 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.
<code class="docutils literal"><span class="pre">anyfield</span></code> - a free-text search variable. The value placed in this parameter will be searched for in any document in any node.
<code class="docutils literal"><span class="pre">pagesize</span></code> - 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.
<code class="docutils literal"><span class="pre">pagestart</span></code> - the displayed search results page (e.g, 1). Used with pagesize. See section 4.3.4 for an example.</p>
</td>
</tr>
<tr class="row-odd"><td>read</td>
<td><p class="first">Get a document from the database and return it in the specified format. See Searching Metacat for an example.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document to return
<code class="docutils literal"><span class="pre">qformat</span></code> - the format to return the document in. Possible values are: <code class="docutils literal"><span class="pre">html</span></code>, <code class="docutils literal"><span class="pre">xml</span></code>,or, if your Metacat uses a skin, the name of the skin.</p>
</td>
</tr>
<tr class="row-even"><td>readinlinedata</td>
<td><p class="first">Read inline data only.</p>
<p class="last"><code class="docutils literal"><span class="pre">inlinedataid</span></code> - the id of the inline data to read</p>
</td>
</tr>
<tr class="row-odd"><td>setaccess</td>
<td><p class="first">Change access permissions for a user on a specified document.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document to be modified.
<code class="docutils literal"><span class="pre">principal</span></code> - the user or group whose permissions will be modified
<code class="docutils literal"><span class="pre">permission</span></code> - the permission to set (read, write, all)
<code class="docutils literal"><span class="pre">permType</span></code> - the type of permission to set (allow, deny)
<code class="docutils literal"><span class="pre">permOrder</span></code> - the order in which to apply the permission (allowFirst, denyFirst)</p>
</td>
</tr>
<tr class="row-even"><td>spatial_query</td>
<td><p class="first">Perform a spatial query. These queries may include any of the queries supported by the
WFS / WMS standards. For more information, see Spatial Queries.</p>
<p class="last"><code class="docutils literal"><span class="pre">xmax</span></code> - max x spatial coordinate
<code class="docutils literal"><span class="pre">ymax</span></code> - max y spatial coordinate
<code class="docutils literal"><span class="pre">xmin</span></code> - min x spatial coordinate
<code class="docutils literal"><span class="pre">ymin</span></code> - min y spatial coordinate</p>
</td>
</tr>
<tr class="row-odd"><td>squery</td>
<td><p class="first">Perform a structured query. For an example, please see Searching Metacat.</p>
<p class="last"><code class="docutils literal"><span class="pre">query</span></code> - the text of the pathquery document sent to the server
<code class="docutils literal"><span class="pre">qformat</span></code> - the format to return the results in. Possible values are: <code class="docutils literal"><span class="pre">xml</span></code>, or the name of the a skin.</p>
</td>
</tr>
<tr class="row-even"><td>update</td>
<td><p class="first">Overwrite an XML document with a new one and give the new one the same docid but with
the next revision number. For an example, please see Inserting, Updating, and
Deleting XML and Data Documents.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document to update
<code class="docutils literal"><span class="pre">doctext</span></code> - the text with which to update the XML document</p>
</td>
</tr>
<tr class="row-odd"><td>upload</td>
<td><p class="first">Upload (insert or update) a data file into Metacat. Data files are stored on Metacat and may be in any
format (binary or text), but they are all treated as if they were binary.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the data file to upload
<code class="docutils literal"><span class="pre">datafile</span></code> - the data file to upload</p>
</td>
</tr>
<tr class="row-even"><td>validate</td>
<td><p class="first">Validate a specified document against its DTD.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document to validate
<code class="docutils literal"><span class="pre">valtext</span></code> - the DTD by which to validate this document</p>
</td>
</tr>
</tbody>
</table>
<p>Metacat Replication Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="9%" />
<col width="91%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Action</th>
<th class="head">Description and Parameters</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>forcereplicate</td>
<td><p class="first">Force the local server to get the specified document from the remote host.</p>
<p class="last"><code class="docutils literal"><span class="pre">server</span></code> - The server to which this document is being sent
<code class="docutils literal"><span class="pre">docid</span></code> - The docid of the document to send
<code class="docutils literal"><span class="pre">dbaction</span></code> - The action to perform on the document: insert or update (the default)</p>
</td>
</tr>
<tr class="row-odd"><td>getall</td>
<td>Force the local server to check all known servers for updated documents. No parameters.</td>
</tr>
<tr class="row-even"><td>getcatalog</td>
<td>Send the contents of the xml_catalog table encoded in XML. No parameters.</td>
</tr>
<tr class="row-odd"><td>getlock</td>
<td><p class="first">Request a lock on the specified document.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document
<code class="docutils literal"><span class="pre">updaterev</span></code> - the revision number of docid</p>
</td>
</tr>
<tr class="row-even"><td>gettime</td>
<td>Return the local time on this server. No parameters.</td>
</tr>
<tr class="row-odd"><td>servercontrol</td>
<td><p class="first">Perform the specified replication control on the Replication daemon.</p>
<p class="last"><code class="docutils literal"><span class="pre">add</span></code> - add a new server to the replication list
<code class="docutils literal"><span class="pre">delete</span></code> - remove a server from the replication list
<code class="docutils literal"><span class="pre">list</span></code> - list all of the servers currently in the server list
<code class="docutils literal"><span class="pre">replicate</span></code> - a Boolean flag (1 or 0) which determines if this server should copy files from the newly added server.
<code class="docutils literal"><span class="pre">server</span></code> - the server to add/delete</p>
</td>
</tr>
<tr class="row-even"><td>read</td>
<td><p class="first">Sends docid to the remote host.</p>
<p class="last"><code class="docutils literal"><span class="pre">docid</span></code> - the docid of the document to read</p>
</td>
</tr>
<tr class="row-odd"><td>start</td>
<td><p class="first">Start the Replication daemon with a time interval of deltaT.</p>
<p class="last"><code class="docutils literal"><span class="pre">rate</span></code> - 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</p>
</td>
</tr>
<tr class="row-even"><td>stop</td>
<td>Stop the Replication daemon. No parameters.</td>
</tr>
<tr class="row-odd"><td>update</td>
<td>Send a list of all documents on the local server along with their revision numbers. No parameters.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="logging-in">
<h3><a class="toc-backref" href="#id18">7.3.2. Logging In</a><a class="headerlink" href="#logging-in" title="Permalink to this headline">¶</a></h3>
<p>To log in to Metacat, use the <code class="docutils literal"><span class="pre">login</span></code> action.</p>
<p>The following is an example of a Web form (see figure) that logs a user into
Metact. Example HTML code is included below the screenshot.</p>
<div class="figure align-center" id="id4">
<img alt="_images/image039.jpg" src="_images/image039.jpg" />
<p class="caption"><span class="caption-text">Logging into Metacat using an HTML form.</span></p>
</div>
<div class="highlight-python"><div class="highlight"><pre><html>
<body>
<form name="loginform" method="post"action="http://yourserver.com/yourcontext/servlet/metacat"
target="_top" onsubmit="return submitform(this);" id="loginform">
<input type="hidden" name="action" value="login"> <input type=
"hidden" name="username" value=""> <input type="hidden" name=
"qformat" value="xml"> <input type="hidden" name=
"enableediting" value="false">
<table>
<tr valign="middle">
<td align="left" valign="middle" class="text_plain">
username:</td>
<td width="173" align="left" class="text_plain" style=
"padding-top: 2px; padding-bottom: 2px;"><input name="uid"
type="text" style="width: 140px;" value=""></td>
</tr>
<tr valign="middle">
<td height="28" align="left" valign="middle" class=
"text_plain">organization:</td>
<td align="left" class="text_plain" style=
"padding-top: 2px; padding-bottom: 2px;"><select name=
"organization" style="width:140px;">
<option value="" selected>&#8212; choose one &#8212;</option>
<option value="NCEAS">NCEAS</option>
<option value="LTER">LTER</option>
<option value="UCNRS">UCNRS</option>
<option value="PISCO">PISCO</option>
<option value="OBFS">OBFS</option>
<option value="OSUBS">OSUBS</option>
<option value="SAEON">SAEON</option>
<option value="SANParks">SANParks</option>
<option value="SDSC">SDSC</option>
<option value="KU">KU</option>
<option value="unaffiliated">unaffiliated</option>
</select></td>
</tr>
<tr valign="middle">
<td width="85" align="left" valign="middle" class=
"text_plain">password:</td>
<td colspan="2" align="left" class="text_plain" style=
"padding-top: 2px; padding-bottom: 2px;">
<table width="100%" border="0" cellpadding="0"
cellspacing="0">
<tr>
<td width="150" align="left"><input name="password"
type="password" maxlength="50" style="width:140px;"
value=""></td>
<td align="center" class="buttonBG_login">
<input type="submit" name="loginAction" value="Login"
class="button_login"></td>
<td align="left">&nbsp;</td>
</tr>
</table>
</td>
</tr>
</table>
</form>
</body>
</html>
</pre></div>
</div>
</div>
<div class="section" id="inserting-updating-and-deleting-xml-and-data-documents">
<h3><a class="toc-backref" href="#id19">7.3.3. Inserting, Updating, and Deleting XML and Data Documents</a><a class="headerlink" href="#inserting-updating-and-deleting-xml-and-data-documents" title="Permalink to this headline">¶</a></h3>
<p>Adding, editing, and deleting XML documents in Metacat can be accomplished
using the insert, update, and delete actions, respectively. Before you can
insert, delete, or update documents, you must log in to Metacat using the
login action. See Logging in for an example.</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">insert</span></code></dt>
<dd>Insert a new XML or data document into Metacat. You must specify a document ID.</dd>
<dt><code class="docutils literal"><span class="pre">update</span></code></dt>
<dd>Update an existing Metacat document. The original document is archived,
then overwritten.</dd>
<dt><code class="docutils literal"><span class="pre">delete</span></code></dt>
<dd>Archive a document and move the pointer in xml_documents to xml_revisions,
effectively “deleting” the document from public view, but preserving the
revision for the revision history. No further updates will be allowed for
the Metacat document that was “deleted”. All revisions of this identifier are no longer
public.</dd>
</dl>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is not possible to “delete” one revision without “deleting” all
revisions of a given identifier.</p>
</div>
<p>The following is an example of a Web form (see figure) that can perform all
three tasks. Example HTML code is included in the sidebar.</p>
<div class="figure align-center" id="id5">
<img alt="_images/image041.jpg" src="_images/image041.jpg" />
<p class="caption"><span class="caption-text">An example of a Web form used to insert, delete, or update XML documents in Metacat.</span></p>
</div>
<div class="highlight-python"><div class="highlight"><pre><html>
<head>
<title>MetaCat</title>
</head>
<body class="emlbody">
<b>MetaCat XML Loader</b>
<p>
Upload, Change, or Delete an XML document using this form.
</p>
<form action="http://yourserver.com/yourcontext/servlet/metacat" method="POST">
<strong>1. Choose an action: </strong>
<input type="radio" name="action" value="insert" checked> Insert
<input type="radio" name="action" value="update"> Update
<input type="radio" name="action" value="delete"> Delete
<input type="submit" value="Process Action">
<br />
<strong>2. Provide a Document ID </strong>
<input type="text" name="docid"> (optional for Insert)
<input type="checkbox" name="public" value="yes" checked><strong>Public Document</strong>
<br />
<strong>3. Provide XML text </strong> (not needed for Delete)<br/>
<textarea name="doctext" cols="65" rows="15"></textarea><br/>
<strong>4. Provide DTD text for upload </strong> (optional; not needed for Delete)
<textarea name="dtdtext" cols="65" rows="15"></textarea>
</form>
</body>
</html>
</pre></div>
</div>
</div>
<div class="section" id="searching-metacat">
<h3><a class="toc-backref" href="#id20">7.3.4. Searching Metacat</a><a class="headerlink" href="#searching-metacat" title="Permalink to this headline">¶</a></h3>
<p>To search Metacat use the <code class="docutils literal"><span class="pre">query</span></code> or <code class="docutils literal"><span class="pre">squery</span></code> actions.</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">query</span></code>:</dt>
<dd>Perform a free text query. Specify the returndoctype, qformat, returnfield,
operator, searchmode, anyfield, and (optionally) a querytitle and doctype.</dd>
<dt><code class="docutils literal"><span class="pre">squery</span></code>:</dt>
<dd>Perform a structured query by submitting an XML pathquery document to the
Metacat server.</dd>
</dl>
<p>When Metacat receives a query via HTTP (screenshot below), the server creates a
“pathquery” document, which is an XML document populated with the specified
search criteria. The pathquery document is then translated into
SQL statements that are executed against the database. Results are translated
into an XML “resultset” document, which can be returned as XML or transformed
into HTML and returned (specify which you would prefer with the returnfield
parameter). You can also opt to submit a pathquery document directly,
using an squery action.</p>
<div class="figure align-center" id="id6">
<img alt="_images/image043.jpg" src="_images/image043.jpg" />
<p class="caption"><span class="caption-text">Example of a basic search form using a query action. The HTML code used to create the form is displayed below.</span></p>
</div>
<div class="highlight-python"><div class="highlight"><pre><html>
<head>
<title>Search</title>
</head>
<body>
<form method="POST" action="http://panucci.nceas.ucsb.edu/metacat/metacat">
Search for:
<input name="action" value="query" type="hidden">
<input name="operator" value="INTERSECT" type="hidden">
<input name="anyfield" type="text" value=" " size="40">
<input name="qformat" value="html" type="hidden">
<input name="returnfield" value="creator/individualName/surName" type="hidden">
<input name="returnfield" value="creator/individualName/givenName" type="hidden">
<input name="returnfield" value="creator/organizationName" type="hidden">
<input name="returnfield" value="dataset/title" type="hidden">
<input name="returnfield" value="keyword" type="hidden">
<input name="returndoctype" value="eml://ecoinformatics.org/eml-2.0.1" type="hidden">
<input value="Start Search" type="submit">
</form>
</body>
</html>
</pre></div>
</div>
<p>Metacat’s pathquery document can query specific fields of any XML document.
The pathquery can also be used to specify which fields from each hit are
returned and displayed in the search result set.</p>
<div class="highlight-python"><div class="highlight"><pre><pathquery version="1.0">
<meta_file_id>unspecified</meta_file_id>
<querytitle>unspecified</querytitle>
<returnfield>dataset/title</returnfield>
<returnfield>keyword</returnfield>
<returnfield>dataset/creator/individualName/surName</returnfield>
<returndoctype>eml://ecoinformatics.org/eml-2.1.0</returndoctype>
<returndoctype>eml://ecoinformatics.org/eml-2.0.1</returndoctype>
<returndoctype>eml://ecoinformatics.org/eml-2.0.0</returndoctype>
<querygroup operator="UNION">
<queryterm casesensitive="true" searchmode="contains">
<value>Charismatic megafauna</value>
<pathexpr>dataset/title</pathexpr>
</queryterm>
<queryterm casesensitive="false" searchmode="starts-with">
<value>sea otter</value>
<pathexpr>keyword</pathexpr>
</queryterm>
<queryterm casesensitive="false" searchmode="contains">
<value>Enhydra</value>
<pathexpr>abstract/para</pathexpr>
</queryterm>
</querygroup>
</pathquery>
</pathquery>
</pre></div>
</div>
<p>Each <code class="docutils literal"><span class="pre"><returnfield></span></code> parameter specifies a field that the database will
return (in addition to the fields Metacat returns by default) for each search
result.</p>
<p>The <code class="docutils literal"><span class="pre"><returndoctype></span></code> field limits the type of returned documents
(eg, eml://ecoinformatics.org/eml-2.0.1 and/or eml://ecoinformatics.org/eml-2.0.0).
If no returndoctype element is specified, all document types are returned.</p>
<p>A <code class="docutils literal"><span class="pre"><querygroup></span></code> creates an AND or an OR statement that applies to the
nested <code class="docutils literal"><span class="pre"><queryterm></span></code> tags. The querygroup operator can be UNION or INTERSECT.
A <code class="docutils literal"><span class="pre"><queryterm></span></code> defines the actual field (contained in <code class="docutils literal"><span class="pre"><pathexpr></span></code> tags)
against which the query (contained in the <code class="docutils literal"><span class="pre"><value></span></code> tags) is being performed.</p>
<p>The <code class="docutils literal"><span class="pre"><pathexpr></span></code> can also contain a document type keyword contained in
<code class="docutils literal"><span class="pre"><returndoc></span></code> tags. The specified document type applies only to documents
that are packaged together (e.g., a data set and its corresponding metadata file).
If Metacat identifies the search term in a packaged document, the servlet will
check to see if that document’s type matches the specified one. If not,
Metacat will check if one of the other documents in the package matches. If so,
Metacat will return the matching document. For more information about packages,
please see the developer documentation.</p>
<p>After Metacat has processed a Pathquery document, it returns a resultset document.</p>
<div class="highlight-python"><div class="highlight"><pre><resultset>
<query>
<pathquery version="1.0">
<meta_file_id>unspecified</meta_file_id>
<querytitle>unspecified</querytitle>
<returnfield>dataset/title</returnfield>
<returnfield>keyword</returnfield>
<returnfield>dataset/creator/individualName/surName</returnfield>
<returndoctype>eml://ecoinformatics.org/eml-2.1.0</returndoctype>
<returndoctype>eml://ecoinformatics.org/eml-2.0.1</returndoctype>
<returndoctype>eml://ecoinformatics.org/eml-2.0.0</returndoctype>
<querygroup operator="UNION">
<queryterm casesensitive="true" searchmode="contains">
<value>Charismatic megafauna</value>
<pathexpr>dataset/title</pathexpr>
</queryterm>
<queryterm casesensitive="false" searchmode="starts-with">
<value>sea otter</value>
<pathexpr>keyword</pathexpr>
</queryterm>
<queryterm casesensitive="false" searchmode="contains">
<value>Enhydra</value>
<pathexpr>abstract/para</pathexpr>
</queryterm>
</querygroup>
</pathquery>
</query>
<document>
<docid>nrs.569.3</docid>
<docname>eml</docname>
<doctype>eml://ecoinformatics.org/eml-2.0.0</doctype>
<createdate>2012-06-06</createdate>
<updatedate>2012-06-06</updatedate>
<param name="dataset/title">Marine Mammal slides</param>
<param name="creator/individualName/surName">Bancroft</param>
</document>
<document>
<docid>knb-lter-sbc.61.1</docid>
<docname>eml</docname>
<doctype>eml://ecoinformatics.org/eml-2.1.0</doctype>
<createdate>2012-06-06</createdate>
<updatedate>2012-06-06</updatedate>
<param name="dataset/creator/individualName/surName">Nelson</param>
<param name="dataset/creator/individualName/surName">Harrer</param>
<param name="dataset/creator/individualName/surName">Reed</param>
<param name="dataset/title">SBC LTER: Reef: Sightings of Sea Otters (Enhydra lutris) near Santa Barbara and Channel Islands, ongoing since 2007</param>
</document>
.....
</resultset>
</pre></div>
</div>
<p>When Metacat returns a resultset document, the servlet always includes the
pathquery used to create it. The pathquery XML is contained in the <query> tag,
the first element in the resultset.</p>
<p>Each XML document returned by the query is represented by a <code class="docutils literal"><span class="pre"><document></span></code> tag. By
default, Metacat will return the docid, docname, doctype, doctitle, createdate
and updatedate for each search result. If the user specified additional return
fields in the pathquery using <code class="docutils literal"><span class="pre"><returnfield></span></code> tags (e.g., dataset/title to return
the document title), the additional fields are returned in <code class="docutils literal"><span class="pre"><param></span></code> tags.</p>
<p>Metacat can return the XML resultset to your client as either XML or HTML.</p>
</div>
<div class="section" id="paged-query-returns">
<h3><a class="toc-backref" href="#id21">7.3.5. Paged Query Returns</a><a class="headerlink" href="#paged-query-returns" title="Permalink to this headline">¶</a></h3>
<p>Dividing large search result sets over a number of pages speeds load-time and
makes the result sets more readable to users (Figure 4.12). To break your search
results into pages, use the query action’s optional pagestart and pagesize
parameters. The pagesize parameter indicates how many results should be
returned for a given page. The pagestart parameter indicates which page you
are currently viewing.</p>
<div class="figure align-center" id="id7">
<img alt="_images/image045.jpg" src="_images/image045.jpg" />
<p class="caption"><span class="caption-text">An example of paged search results.</span></p>
</div>
<p>When a paged query is performed, the query’s resultset contains four extra
fields: pagestart, pagesize, nextpage, and previouspage (Figure 4.13). The
nextpage and previouspage fields help Metacat generate navigational links in
the rendered resultset using XSLT to transform the XML to HTML.</p>
<div class="highlight-python"><div class="highlight"><pre><!-- An example of an XML resultset that include support for page breaks.
The pagestart parameter will always indicate the page you are currently viewing.
-->
<resultset>
<pagestart>1</pagestart>
<pagesize>10</pagesize>
<nextpage>2</nextpage>
<previouspage>0</previouspage>
<query> ...</query>
<document>...</document>
<document>...</document>
</resultset>
</pre></div>
</div>
<p>The HTML search results displayed in the figure were rendered using Kepler’s XSLT,
which can be found in lib/style/skins/kepler. Kepler’s XSLT uses the four extra
resultset fields to render the “Next” and “Previous” links.</p>
<div class="highlight-python"><div class="highlight"><pre><a href="metacat?action=query&operator=INTERSECT&enableediting=false&anyfield=actor&qformat=kepler&pagestart=0&pagesize=10">Previous Page</a>
<a href="metacat?action=query&operator=INTERSECT&enableediting=false&anyfield=actor&qformat=kepler&pagestart=2&pagesize=10">Next Page</a>
</pre></div>
</div>
<p>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.</p>
</div>
<div class="section" id="reading-data-and-metadata">
<h3><a class="toc-backref" href="#id22">7.3.6. Reading Data and Metadata</a><a class="headerlink" href="#reading-data-and-metadata" title="Permalink to this headline">¶</a></h3>
<p>To read data or metadata from Metacat, use the <code class="docutils literal"><span class="pre">read</span></code> action. The <code class="docutils literal"><span class="pre">read</span></code> action
takes two parameters: <code class="docutils literal"><span class="pre">docid</span></code>, which specifies the document ID of the document
to return, and <code class="docutils literal"><span class="pre">qformat</span></code>, which specifies the return format for the document
(<code class="docutils literal"><span class="pre">html</span></code> or <code class="docutils literal"><span class="pre">xml</span></code> or the name of a configured style-set, e.g., <code class="docutils literal"><span class="pre">default</span></code>). If <code class="docutils literal"><span class="pre">qformat</span></code>
is set to <code class="docutils literal"><span class="pre">xml</span></code>, Metacat will return the XML document untransformed. If the
return format is set to <code class="docutils literal"><span class="pre">html</span></code>, Metacat will transform the XML document into
HTML using the default XSLT style sheet (specified in the Metacat
configuration). If the name of a style-set is specified, Metacat will use the
XSLT styles specified in the set to transform the XML.</p>
<div class="figure align-center" id="id8">
<img alt="_images/image047.jpg" src="_images/image047.jpg" />
<p class="caption"><span class="caption-text">The same document displayed using different qformat parameters (from left
to right: the default style-set, XML, and HTML).</span></p>
</div>
<p>Note that the <code class="docutils literal"><span class="pre">read</span></code> action can be used to read both data files and metadata files.
To read a data file, you could use the following request:</p>
<div class="highlight-python"><div class="highlight"><pre>http://yourserver.com/yourcontext/metacat?action=read&docid=nceas.55&qformat=default
</pre></div>
</div>
<p>Where <code class="docutils literal"><span class="pre">nceas.55</span></code> is the docid of the data file stored in the Metacat and
<code class="docutils literal"><span class="pre">default</span></code> is the name of the style (you could also use “html” or “xml” or the
name of a customized skin).</p>
<div class="highlight-python"><div class="highlight"><pre><html>
<head>
<title>Read Document</title>
</head>
<body>
<form method="POST" action="http://your.server/your.context/servlet/metacat">
<input name="action" value="read" type="hidden">
<input name="docid" type="text" value="" size="40">
<input name="qformat" value="default" type="hidden">
<input value="Read" type="submit">
</form>
</body>
</html>
</pre></div>
</div>
</div>
</div>
<div class="section" id="using-the-earthgrid-api-aka-ecogrid">
<h2><a class="toc-backref" href="#id23">7.4. Using the EarthGrid API (aka EcoGrid)</a><a class="headerlink" href="#using-the-earthgrid-api-aka-ecogrid" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The EarthGrid/EcoGrid web service API is <em>deprecated</em> as of Metacat 2.0.0 and
will be removed from a future version of Metacat. Its functionality is being
replaced by the standardized DataONE REST service interface. The EarthGrid API
will be completely removed by the end of 2013.</p>
</div>
<p>The EarthGrid (aka EcoGrid) provides access to disparate data on different
networks (e.g., KNB, GBIF, GEON) and storage systems (e.g., Metacat and SRB),
allowing scientists access to a wide variety of data and analytic resources
(e.g., data, metadata, analytic workflows and processors) networked at different
sites and at different organizations via the internet.</p>
<p>Because Metacat supports the EarthGrid API (see table), it can query the
distributed EarthGrid, retrieve metadata and data results, and write new and
updated metadata and data back to the grid nodes.</p>
<p>For more information about each EarthGrid service and its WSDL file, navigate
to the “services” page on your Metacat server
(e.g., <a class="reference external" href="http://knb.ecoinformatics.org/metacat/services">http://knb.ecoinformatics.org/metacat/services</a>).
Note that the AdminService and Version service that appear on this page are
not part of EarthGrid.</p>
<p>EarthGrid/EcoGrid API Summary</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="78%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Service</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>AuthenticationQueryService</td>
<td><p class="first">Search for and retrieve protected metadata and data from the EarthGrid as an authenticated user.</p>
<p class="last">Methods: <code class="docutils literal"><span class="pre">query</span></code>, <code class="docutils literal"><span class="pre">get</span></code></p>
</td>
</tr>
<tr class="row-odd"><td>AuthenticationService</td>
<td><p class="first">Log in and out of the EarthGrid</p>
<p class="last">Methods: <code class="docutils literal"><span class="pre">login</span></code>, <code class="docutils literal"><span class="pre">logout</span></code></p>
</td>
</tr>
<tr class="row-even"><td>IdentifierService</td>
<td><p class="first">List, lookup, validate, and add Life Science Identifiers (LSIDs) to the EarthGrid</p>
<p class="last">Methods: <code class="docutils literal"><span class="pre">isRegistered</span></code>, <code class="docutils literal"><span class="pre">addLSID</span></code>, <code class="docutils literal"><span class="pre">getNextRevision</span></code>, <code class="docutils literal"><span class="pre">getNextObject</span></code>, <code class="docutils literal"><span class="pre">getAllIds</span></code></p>
</td>
</tr>
<tr class="row-odd"><td>PutService</td>
<td><p class="first">Write metadata to the EarthGrid</p>
<p class="last">Methods: <code class="docutils literal"><span class="pre">put</span></code></p>
</td>
</tr>
<tr class="row-even"><td>QueryService</td>
<td><p class="first">Search for and retrieve metadata from the EarthGrid</p>
<p class="last">Methods: <code class="docutils literal"><span class="pre">query</span></code>, <code class="docutils literal"><span class="pre">get</span></code></p>
</td>
</tr>
<tr class="row-odd"><td>RegistryService</td>
<td><p class="first">Add, update, remove, and search for registered EarthGrid services.
Note: The WSDL for this service is found under <a class="reference external" href="http://ecogrid.ecoinformatics.org/registry/services">http://ecogrid.ecoinformatics.org/registry/services</a></p>
<p class="last">Methods: <code class="docutils literal"><span class="pre">add</span></code>, <code class="docutils literal"><span class="pre">update</span></code>, <code class="docutils literal"><span class="pre">remove</span></code>, <code class="docutils literal"><span class="pre">list</span></code>, <code class="docutils literal"><span class="pre">query</span></code></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="using-morpho">
<h2><a class="toc-backref" href="#id24">7.5. Using Morpho</a><a class="headerlink" href="#using-morpho" title="Permalink to this headline">¶</a></h2>
<p>Morpho is a desktop tool created to facilitate the creation, storage, and
retrieval of metadata. Morpho interfaces with any Metacat server, allowing
users to upload, download, store, query and view relevant metadata and data
using the network. Users can authorize the public or only selected colleagues
to view their data files.</p>
<p>Morpho is part of the Knowledge Network for Biocomplexity (KNB), a national
network intended to facilitate ecological and environmental research on
biocomplexity. To use Morpho with your Metacat, set the Metacat URL in the
Morpho Preferences to point to your Metacat server.</p>
<div class="figure align-center" id="id9">
<img alt="_images/image049.png" src="_images/image049.png" />
<p class="caption"><span class="caption-text">Set the Metacat URL in the Morpho preferences to point to your Metacat.</span></p>
</div>
<p>For more information about Morpho, please see: <a class="reference external" href="http://knb.ecoinformatics.org/">http://knb.ecoinformatics.org/</a></p>
</div>
<div class="section" id="creating-your-own-client">
<h2><a class="toc-backref" href="#id25">7.6. Creating Your Own Client</a><a class="headerlink" href="#creating-your-own-client" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">NOTE: The Client API (and underlying servlet implementation) has been
deprecated as of Metacat 2.0.0. Future development should utilize the DataONE
REST service methods. The Client API will be completely removed by the end of 2013.</p>
</div>
<p>Metacat’s client API is available in Java and Perl (the Java interface is
described in this section and further detailed in the appendix). Some of the
API is also available in Python and Ruby. The API allows client applications
to easily authenticate users and perform basic Metacat operations such as
reading metadata and data files; inserting, updating, and deleting files; and
searching for packages based on metadata matches.</p>
<p>The Client API is defined by the interface edu.ucsb.nceas.metacat.client.Metacat,
and all operations are fully defined in the <a class="reference external" href="http://knb.ecoinformatics.org/software/metacat/dev/api/index.html">javadoc</a> documentation. To use the
client API, include the <code class="docutils literal"><span class="pre">metacat-client.jar</span></code>, <code class="docutils literal"><span class="pre">utilities.jar</span></code>, <code class="docutils literal"><span class="pre">commons-io-2.0.jar</span></code>, and
<code class="docutils literal"><span class="pre">httpclient.jar</span></code> in your classpath. After including these classes, you can
begin using the API methods (see the next table).</p>
<p>The following code block displays a typical session for reading a document
from Metacat using the Java client API.</p>
<div class="highlight-python"><div class="highlight"><pre>String metacatUrl = "http://foo.com/context/metacat";
String username = "uid=jones,o=NCEAS,dc=ecoinformatics,dc=org";
String password = "neverHarcodeAPasswordInCode";
try {
Metacat m = MetacatFactory.createMetacatConnection(metacatUrl);
m.login(username, password);
Reader r = m.read("testdocument.1.1");
// Do whatever you want with Reader r
} catch (MetacatAuthException mae) {
handleError("Authorization failed:\n" + mae.getMessage());
} catch (MetacatInaccessibleException mie) {
handleError("Metacat Inaccessible:\n" + mie.getMessage());
} catch (Exception e) {
handleError("General exception:\n" + e.getMessage());
}
Operations provided by Client API (Metacat.java class)
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="6%" />
<col width="56%" />
<col width="38%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Method</th>
<th class="head">Parameters and Throws</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>delete</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">delete(String</span> <span class="pre">docid)</span> <span class="pre">throws</span> <span class="pre">InsufficientKarmaException,</span> <span class="pre">MetacatException,</span> <span class="pre">MetacatInaccessibleException;</span></code></td>
<td>Delete an XML document in the repository.</td>
</tr>
<tr class="row-odd"><td>getAllDocids</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">Vector</span> <span class="pre">getAllDocids(String</span> <span class="pre">scope)</span> <span class="pre">throws</span> <span class="pre">MetacatException;</span></code></td>
<td>Return a list of all docids that match a given scope. If scope is null, return all docids registered in the system.</td>
</tr>
<tr class="row-even"><td>getLastDocid</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">getLastDocid(String</span> <span class="pre">scope)</span> <span class="pre">throws</span> <span class="pre">MetacatException;</span></code></td>
<td>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.</td>
</tr>
<tr class="row-odd"><td>getloggedinuserinfo</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">getloggedinuserinfo()</span> <span class="pre">throws</span> <span class="pre">MetacatInaccessibleException;</span></code></td>
<td>Return the logged in user for this session.</td>
</tr>
<tr class="row-even"><td>getNewestDocRevision</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">int</span> <span class="pre">getNewestDocRevision(String</span> <span class="pre">docId)</span> <span class="pre">throws</span> <span class="pre">MetacatException;</span></code></td>
<td>Return the latest revision of specified the document from Metacat</td>
</tr>
<tr class="row-odd"><td>getSessonId</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">getSessionId();</span></code></td>
<td>Return the session identifier for this session.</td>
</tr>
<tr class="row-even"><td>insert</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">insert(String</span> <span class="pre">docid,</span> <span class="pre">Reader</span> <span class="pre">xmlDocument,</span> <span class="pre">Reader</span> <span class="pre">schema)</span> <span class="pre">throws</span> <span class="pre">InsufficientKarmaException,</span> <span class="pre">MetacatException,</span> <span class="pre">IOException,</span> <span class="pre">MetacatInaccessibleException;</span></code></td>
<td>Insert an XML document into the repository.</td>
</tr>
<tr class="row-odd"><td>isRegistered</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">boolean</span> <span class="pre">isRegistered(String</span> <span class="pre">docid)</span> <span class="pre">throws</span> <span class="pre">MetacatException;</span></code></td>
<td>Return true if given docid is registered; false if not.</td>
</tr>
<tr class="row-even"><td>login</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">login(String</span> <span class="pre">username,</span> <span class="pre">String</span> <span class="pre">password)</span> <span class="pre">throws</span> <span class="pre">MetacatAuthException,</span> <span class="pre">MetacatInaccessibleException;</span></code></td>
<td>Log in to a Metacat server.</td>
</tr>
<tr class="row-odd"><td>logout</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">logout()</span> <span class="pre">throws</span> <span class="pre">MetacatInaccessibleException,</span> <span class="pre">MetacatException;</span></code></td>
<td>Log out of a Metacat server.</td>
</tr>
<tr class="row-even"><td>query</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">Reader</span> <span class="pre">query(Reader</span> <span class="pre">xmlQuery)</span> <span class="pre">throws</span> <span class="pre">MetacatInaccessibleException,</span> <span class="pre">IOException;</span></code></td>
<td>Query the Metacat repository and return the result set as a Reader.</td>
</tr>
<tr class="row-odd"><td>query</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">Reader</span> <span class="pre">query(Reader</span> <span class="pre">xmlQuery,</span> <span class="pre">String</span> <span class="pre">qformat)</span> <span class="pre">throws</span> <span class="pre">MetacatInaccessibleException,</span> <span class="pre">IOException;</span></code></td>
<td>Query the Metacat repository with the given metacat-compatible query format and return the result set as a Reader.</td>
</tr>
<tr class="row-even"><td>read</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">Reader</span> <span class="pre">read(String</span> <span class="pre">docid)</span> <span class="pre">throws</span> <span class="pre">InsufficientKarmaException,</span> <span class="pre">MetacatInaccessibleException,</span> <span class="pre">DocumentNotFoundException,</span> <span class="pre">MetacatException;</span></code></td>
<td>Read an XML document from the Metacat server.</td>
</tr>
<tr class="row-odd"><td>readInlineData</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">Reader</span> <span class="pre">readInlineData(String</span> <span class="pre">inlinedataid)</span> <span class="pre">throws</span> <span class="pre">InsufficientKarmaException,</span> <span class="pre">MetacatInaccessibleException,</span> <span class="pre">MetacatException;</span></code></td>
<td>Read inline data from the Metacat server session.</td>
</tr>
<tr class="row-even"><td>setAccess</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">setAccess(String</span> <span class="pre">_docid,</span> <span class="pre">String</span> <span class="pre">_principal,</span> <span class="pre">String</span> <span class="pre">_permission,</span> <span class="pre">String</span> <span class="pre">_permType,</span> <span class="pre">String</span> <span class="pre">_permOrder</span> <span class="pre">);</span> <span class="pre">throws</span> <span class="pre">InsufficientKarmaException,</span> <span class="pre">MetacatException,</span> <span class="pre">MetacatInaccessibleException;</span></code></td>
<td>Set permissions for an XML document in the Metacat repository.</td>
</tr>
<tr class="row-odd"><td>setMetacatUrl</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">void</span> <span class="pre">setMetacatUrl(String</span> <span class="pre">metacatUrl);</span></code></td>
<td>Set the MetacatUrl to which connections should be made.</td>
</tr>
<tr class="row-even"><td>setSessionId</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">void</span> <span class="pre">setSessionId(String</span> <span class="pre">sessionId);</span></code></td>
<td>Set the session identifier for this session.</td>
</tr>
<tr class="row-odd"><td>update</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">update(String</span> <span class="pre">docid,</span> <span class="pre">Reader</span> <span class="pre">xmlDocument,</span> <span class="pre">Reader</span> <span class="pre">schema)</span> <span class="pre">throws</span> <span class="pre">InsufficientKarmaException,</span> <span class="pre">MetacatException,</span> <span class="pre">IOException,</span> <span class="pre">MetacatInaccessibleException;</span></code></td>
<td>Update an XML document in the repository by providing a new version of the XML document.</td>
</tr>
<tr class="row-even"><td>upload</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">upload(String</span> <span class="pre">docid,</span> <span class="pre">File</span> <span class="pre">file)</span> <span class="pre">throws</span> <span class="pre">InsufficientKarmaException,</span> <span class="pre">MetacatException,</span> <span class="pre">IOException,</span> <span class="pre">MetacatInaccessibleException;</span></code></td>
<td>Upload a data document into the repository.</td>
</tr>
<tr class="row-odd"><td>upload</td>
<td><code class="docutils literal"><span class="pre">public</span> <span class="pre">String</span> <span class="pre">publicupload(String</span> <span class="pre">docid,</span> <span class="pre">String</span> <span class="pre">fileName,</span> <span class="pre">InputStream</span> <span class="pre">fileData,</span> <span class="pre">int</span> <span class="pre">size)</span> <span class="pre">throws</span> <span class="pre">InsufficientKarmaException,</span> <span class="pre">MetacatException,</span> <span class="pre">IOException,</span> <span class="pre">MetacatInaccessibleException;</span></code></td>
<td>Upload a data document into the repository.</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
<div class="footerNav">
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right">
<span id="searchbox" style="display: none;">
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" class="icon-search"/>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</span>
</li>
<script type="text/javascript">$('#searchbox').show(0);</script>
<li class="right">
<a href="genindex.html" title="General Index"
>index</a>
</li>
<li class="right">
<a href="query-index.html" title="8. Metacat Indexing"
>next</a>
</li>
<li class="right">
<a href="dataone.html" title="6. DataONE Member Node Support"
>previous</a>
</li>
<li class="breadcrumb first"><a href="index.html">Metacat 2.8.1 documentation</a> »</li>
</ul>
</div>
</div>
<div class="small-print">
© Copyright 2012, Regents of the University of California.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.1.
</div>
</div>
</div>
</body>
</html>