Class Metacat
In: lib/metacat.rb
Parent: Object

Metacat Client Library

What is it

A client for the Metacat data catalog. For a description of Metacat, see knb.ecoinformatics.org/software/metacat For now, this client does not implement all features of the API. Rather, it focuses on querying and returning Eml metadata objects from either pathqueries or docid’s. Should you find yourself using methods other than find() very often, you may be veering from the original intent.

Examples

Read metadata for a public document

  require 'lib/metacat.rb'
  metacat = Metacat.new('http://data.piscoweb.org/catalog/metacat')
  eml = metacat.find(:docid => 'pisco.10.4')
  puts eml.docid
  => 'pisco.10.4'

Log into Metacat and read Eml metadata. Then logout

  username = 'uid=cburt,o=PISCO,dc=ecoinformatic,dc=org'
  password = *****
  Metacat.new('http://data.piscoweb.org/catalog/metacat', username, password) do |metacat|
    eml = metacat.find(:docid => 'pisco.10.3')
    start, end = eml.temporal_coverage
    puts "start: #{start}, end: #{end}"
  end

Search for oceanographic data

  metacat = Metacat.new('http://data.piscoweb.org/catalog/metacat')
  pathquery = '...' # see example at http://knb.ecoinformatics.org/software/metacat/metacatquery.html
  docs = metacat.find(:squery => pathquery)
  docs.each { |eml| puts eml.docid }

Find and write a data_table to local disk

  Metacat.new('http://data.piscoweb.org/catalog/metacat', username, password) do |metacat|
    file = File.new('tmp', 'w+')
    # using a block you can avoid loading the whole file into memory!
    metacat.read('data_table.1.1') do |fragment|
      file.write(fragment)
    end
    file.close
  end

Methods

find   logged_in?   login   logout   new   read   squery  

Public Class methods

Public Instance methods

find(args)

Returns either an array of Eml documents(or nil) if :squery is passed or a single Eml document(or nil) if passed :docid. This function will not return a data table, only Eml objects.

If you need to retrieve a data table or other document, use read()

Examples: 

  Metacat.find(:docid => 'cbs_10.1')
  Metacat.find(:squery => xml_path_query)
logged_in?()

Check if the metacat instance has a session cookie

login(username, password)

Logs into metacat using ldap authentication. Usernames are complex, such as ‘uid=cburt,o=PISCO,dc=ecoinformatics,dc=org’

Raises MetacatPermissionDenied exception on fail

Example 

  metacat.login('uid=cburt,o=PISCO,dc=ecoinformatics,dc=org', '******')
  => true
read(docid, options = {}) {|xml or data_table fragment| ...}

Reads a specified document from metacat. If xml is found, a REXML::Document will be returned

When reading text data tables, it should be noted that loading the entire large file can consume an enormous amount of memory. To avoid this, read can be passed a &block. The block will recieve fragments of the file as it comes in.

Examples: Reading an EML document 

  metacat.read('eml_doc.1.1')
  => <REXML::Document >

Writing a data table to disk 

  file = File.new('tmp', 'w+')
  metacat.read('data_table.1.1') do |fragment|
    file.write(fragment)
  end
  file.close

Reading an entire data table into memory 

  data_table = metacat.read('data_table.1.1')
squery(squery)

Uses the metacat pathquery search and returns the xml response as a string. For query format information, see knb.ecoinformatics.org/software/metacat/metacatquery.html

[Validate]