Project

General

Profile

1 3132 perry
<?xml version="1.0" encoding="iso-8859-1"?>
2
<!DOCTYPE html
3
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7
<head>
8
  <title>Class: Metacat</title>
9
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
10
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
11
  <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
12
  <script type="text/javascript">
13
  // <![CDATA[
14
15
  function popupCode( url ) {
16
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
17
  }
18
19
  function toggleCode( id ) {
20
    if ( document.getElementById )
21
      elem = document.getElementById( id );
22
    else if ( document.all )
23
      elem = eval( "document.all." + id );
24
    else
25
      return false;
26
27
    elemStyle = elem.style;
28
29
    if ( elemStyle.display != "block" ) {
30
      elemStyle.display = "block"
31
    } else {
32
      elemStyle.display = "none"
33
    }
34
35
    return true;
36
  }
37
38
  // Make codeblocks hidden by default
39
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
40
41
  // ]]>
42
  </script>
43
44
</head>
45
<body>
46
47
48
49
    <div id="classHeader">
50
        <table class="header-table">
51
        <tr class="top-aligned-row">
52
          <td><strong>Class</strong></td>
53
          <td class="class-name-in-header">Metacat</td>
54
        </tr>
55
        <tr class="top-aligned-row">
56
            <td><strong>In:</strong></td>
57
            <td>
58
                <a href="../files/lib/metacat_rb.html">
59
                lib/metacat.rb
60
                </a>
61
        <br />
62
            </td>
63
        </tr>
64
65
        <tr class="top-aligned-row">
66
            <td><strong>Parent:</strong></td>
67
            <td>
68
                Object
69
            </td>
70
        </tr>
71
        </table>
72
    </div>
73
  <!-- banner header -->
74
75
  <div id="bodyContent">
76
77
78
79
  <div id="contextContent">
80
81
    <div id="description">
82
      <h1><a href="Metacat.html">Metacat</a> Client Library</h1>
83
<h2>What is it</h2>
84
<p>
85
A client for the <a href="Metacat.html">Metacat</a> data catalog. For a
86
description of <a href="Metacat.html">Metacat</a>, see <a
87
href="http://knb.ecoinformatics.org/software/metacat">knb.ecoinformatics.org/software/metacat</a>
88
For now, this client does not implement all features of the API. Rather, it
89
focuses on querying and returning <a href="Eml.html">Eml</a> metadata
90
objects from either pathqueries or docid&#8217;s. Should you find yourself
91
using methods other than find() very often, you may be veering from the
92
original intent.
93
</p>
94
<h2>Examples</h2>
95
<h3>Read metadata for a public document</h3>
96
<pre>
97
  require 'lib/metacat.rb'
98
  metacat = Metacat.new('http://data.piscoweb.org/catalog/metacat')
99
  eml = metacat.find(:docid =&gt; 'pisco.10.4')
100
  puts eml.docid
101
  =&gt; 'pisco.10.4'
102
</pre>
103
<h3>Log into <a href="Metacat.html">Metacat</a> and read <a href="Eml.html">Eml</a> metadata. Then logout</h3>
104
<pre>
105
  username = 'uid=cburt,o=PISCO,dc=ecoinformatic,dc=org'
106
  password = *****
107
  Metacat.new('http://data.piscoweb.org/catalog/metacat', username, password) do |metacat|
108
    eml = metacat.find(:docid =&gt; 'pisco.10.3')
109
    start, end = eml.temporal_coverage
110
    puts &quot;start: #{start}, end: #{end}&quot;
111
  end
112
</pre>
113
<h3>Search for oceanographic data</h3>
114
<pre>
115
  metacat = Metacat.new('http://data.piscoweb.org/catalog/metacat')
116
  pathquery = '...' # see example at http://knb.ecoinformatics.org/software/metacat/metacatquery.html
117
  docs = metacat.find(:squery =&gt; pathquery)
118
  docs.each { |eml| puts eml.docid }
119
</pre>
120
<h3>Find and write a data_table to local disk</h3>
121
<pre>
122
  Metacat.new('http://data.piscoweb.org/catalog/metacat', username, password) do |metacat|
123
    file = File.new('tmp', 'w+')
124
    # using a block you can avoid loading the whole file into memory!
125
    metacat.read('data_table.1.1') do |fragment|
126
      file.write(fragment)
127
    end
128
    file.close
129
  end
130
</pre>
131
132
    </div>
133
134
135
   </div>
136
137
    <div id="method-list">
138
      <h3 class="section-bar">Methods</h3>
139
140
      <div class="name-list">
141
      <a href="#M000072">find</a>&nbsp;&nbsp;
142
      <a href="#M000071">logged_in?</a>&nbsp;&nbsp;
143
      <a href="#M000073">login</a>&nbsp;&nbsp;
144
      <a href="#M000074">logout</a>&nbsp;&nbsp;
145
      <a href="#M000070">new</a>&nbsp;&nbsp;
146
      <a href="#M000075">read</a>&nbsp;&nbsp;
147
      <a href="#M000076">squery</a>&nbsp;&nbsp;
148
      </div>
149
    </div>
150
151
  </div>
152
153
154
    <!-- if includes -->
155
156
    <div id="section">
157
158
159
160
161
162
163
164
165
    <!-- if method_list -->
166
    <div id="methods">
167
      <h3 class="section-bar">Public Class methods</h3>
168
169
      <div id="method-M000070" class="method-detail">
170
        <a name="M000070"></a>
171
172
        <div class="method-heading">
173
          <a href="Metacat.src/M000070.html" target="Code" class="method-signature"
174
            onclick="popupCode('Metacat.src/M000070.html');return false;">
175
          <span class="method-name">new</span><span class="method-args">(path_to_metacat, options = {}) {|self| ...}</span>
176
          </a>
177
        </div>
178
179
        <div class="method-description">
180
        </div>
181
      </div>
182
183
      <h3 class="section-bar">Public Instance methods</h3>
184
185
      <div id="method-M000072" class="method-detail">
186
        <a name="M000072"></a>
187
188
        <div class="method-heading">
189
          <a href="Metacat.src/M000072.html" target="Code" class="method-signature"
190
            onclick="popupCode('Metacat.src/M000072.html');return false;">
191
          <span class="method-name">find</span><span class="method-args">(args)</span>
192
          </a>
193
        </div>
194
195
        <div class="method-description">
196
          <p>
197
Returns either an array of <a href="Eml.html">Eml</a> documents(or nil) if
198
:squery is passed or a single <a href="Eml.html">Eml</a> document(or nil)
199
if passed :docid. This function <em>will</em> <em>not</em> return a data
200
table, only <a href="Eml.html">Eml</a> objects.
201
</p>
202
<p>
203
If you need to retrieve a data table or other document, use read()
204
</p>
205
<p>
206
Examples:
207
</p>
208
<pre>
209
  Metacat.find(:docid =&gt; 'cbs_10.1')
210
  Metacat.find(:squery =&gt; xml_path_query)
211
</pre>
212
        </div>
213
      </div>
214
215
      <div id="method-M000071" class="method-detail">
216
        <a name="M000071"></a>
217
218
        <div class="method-heading">
219
          <a href="Metacat.src/M000071.html" target="Code" class="method-signature"
220
            onclick="popupCode('Metacat.src/M000071.html');return false;">
221
          <span class="method-name">logged_in?</span><span class="method-args">()</span>
222
          </a>
223
        </div>
224
225
        <div class="method-description">
226
          <p>
227
Check if the metacat instance has a session cookie
228
</p>
229
        </div>
230
      </div>
231
232
      <div id="method-M000073" class="method-detail">
233
        <a name="M000073"></a>
234
235
        <div class="method-heading">
236
          <a href="Metacat.src/M000073.html" target="Code" class="method-signature"
237
            onclick="popupCode('Metacat.src/M000073.html');return false;">
238
          <span class="method-name">login</span><span class="method-args">(username, password)</span>
239
          </a>
240
        </div>
241
242
        <div class="method-description">
243
          <p>
244
Logs into metacat using ldap authentication. Usernames are complex, such as
245
&#8216;uid=cburt,o=PISCO,dc=ecoinformatics,dc=org&#8217;
246
</p>
247
<p>
248
Raises <a href="MetacatPermissionDenied.html">MetacatPermissionDenied</a>
249
exception on fail
250
</p>
251
<p>
252
Example
253
</p>
254
<pre>
255
  metacat.login('uid=cburt,o=PISCO,dc=ecoinformatics,dc=org', '******')
256
  =&gt; true
257
</pre>
258
        </div>
259
      </div>
260
261
      <div id="method-M000074" class="method-detail">
262
        <a name="M000074"></a>
263
264
        <div class="method-heading">
265
          <a href="Metacat.src/M000074.html" target="Code" class="method-signature"
266
            onclick="popupCode('Metacat.src/M000074.html');return false;">
267
          <span class="method-name">logout</span><span class="method-args">()</span>
268
          </a>
269
        </div>
270
271
        <div class="method-description">
272
        </div>
273
      </div>
274
275
      <div id="method-M000075" class="method-detail">
276
        <a name="M000075"></a>
277
278
        <div class="method-heading">
279
          <a href="Metacat.src/M000075.html" target="Code" class="method-signature"
280
            onclick="popupCode('Metacat.src/M000075.html');return false;">
281
          <span class="method-name">read</span><span class="method-args">(docid, options = {}) {|xml or data_table fragment| ...}</span>
282
          </a>
283
        </div>
284
285
        <div class="method-description">
286
          <p>
287
Reads a specified document from metacat. If xml is found, a REXML::Document
288
will be returned
289
</p>
290
<p>
291
When reading text data tables, it should be noted that loading the entire
292
large file can consume an enormous amount of memory. To avoid this, read
293
can be passed a &amp;block. The block will recieve fragments of the file as
294
it comes in.
295
</p>
296
<p>
297
Examples: Reading an EML document
298
</p>
299
<pre>
300
  metacat.read('eml_doc.1.1')
301
  =&gt; &lt;REXML::Document &gt;
302
</pre>
303
<p>
304
Writing a data table to disk
305
</p>
306
<pre>
307
  file = File.new('tmp', 'w+')
308
  metacat.read('data_table.1.1') do |fragment|
309
    file.write(fragment)
310
  end
311
  file.close
312
</pre>
313
<p>
314
Reading an entire data table into memory
315
</p>
316
<pre>
317
  data_table = metacat.read('data_table.1.1')
318
</pre>
319
        </div>
320
      </div>
321
322
      <div id="method-M000076" class="method-detail">
323
        <a name="M000076"></a>
324
325
        <div class="method-heading">
326
          <a href="Metacat.src/M000076.html" target="Code" class="method-signature"
327
            onclick="popupCode('Metacat.src/M000076.html');return false;">
328
          <span class="method-name">squery</span><span class="method-args">(squery)</span>
329
          </a>
330
        </div>
331
332
        <div class="method-description">
333
          <p>
334
Uses the metacat pathquery search and returns the xml response as a string.
335
For query format information, see <a
336
href="http://knb.ecoinformatics.org/software/metacat/metacatquery.html">knb.ecoinformatics.org/software/metacat/metacatquery.html</a>
337
</p>
338
        </div>
339
      </div>
340
341
342
    </div>
343
344
345
  </div>
346
347
348
<div id="validator-badges">
349
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
350
</div>
351
352
</body>
353
</html>