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

new(path_to_metacat, options = {}) {|self| ...}

### 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

logout()
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]