solrizer-fedora

h1. solrizer-fedora

An extension to projecthydra/solrizer that provides utilities for loading objects from Fedora Repositories and creating solr documents from them.

h2. Installation

The gem is hosted on rubygems.org. The best way to manage the gems for your project is to use bundler. Create a Gemfile in the root of your application and include the following:

source "http://rubygems.org"

gem 'solrizer-fedora'

Then:

bundle install

h2. Pre-requisite to Use of Solrizer-Fedora

In order to use solrizer-fedora, you must have a Solr and a Fedora instance available. The easiest approach is to set up an instance of "hydra-jetty":https://github.com/projecthydra/hydra-jetty.

h3. Setup local hydra-jetty

In order to use solrizer-fedora, you must first set up an instance of "hydra-jetty":https://github.com/projecthydra/hydra-jetty.

Once you have set this up, cd into the directory and type:

java -jar start.jar

You must tell the app where to find fedora and solr. Put that information into config/fedora.yml and config/solr.yml:

Sample config files:

config/fedora.yml

development:
  fedora:
    url: http://fedoraAdmin:fedoraAdmin@127.0.0.1:8983/fedora
  solr:
    url: http://127.0.0.1:8983/solr/development
test:
  fedora:
    url: http://fedoraAdmin:fedoraAdmin@127.0.0.1:8983/fedora
  solr:
    url: http://127.0.0.1:8983/solr/test
production:
  fedora:
    url: http://fedoraAdmin:fedoraAdmin@127.0.0.1:8080/fedora
  solr:
    url: http://127.0.0.1:8080/solr

config/solr.yml

development:
  default:
    url: http://localhost:8983/solr
  full_text:
    url: http://localhost:8983/solr
test: &TEST
  default:
    url: http://localhost:8983/solr
  full_text:
    url: http://localhost:8983/solr
production:
  default:
    url: http://localhost:8080/solr/production 
  full_text:
    url: http://localhost:8080/solr/production 

h2. Usage

h3. Fire up the console:

Start up a console and load solrizer-fedora:

irb
require "rubygems"
require "solrizer-fedora"

Initialize ActiveFedora:

ActiveFedora.init

h3. Create an instance of Solrizer::Fedora::Solrizer:

solrizer = Solrizer::Fedora::Solrizer.new

Or, if you want to index full text rather than just fields (and you have provided a full text solr index in your solr.yml):

full_text_solrizer = Solrizer::Fedora::Solrizer.new(:index_full_text=>true)

h3. Solrizing a single object in your repository:

If you have an existing object in your repository, you can solrize it by passing its pid:

solrizer.solrize "demo:5"

If you have either an instance of ActiveFedora::Base or Fedora::Object, you can solrize it by passing the object itself:

my_object = ActiveFedora::Base.new

solrizer.solrize my_object

To view the resulting document, open a web browser and go to the jetty's solr admin page (most likely http://localhost/solr/admin) and query your solr instance for the pid (e.g. id:demo:5).

h3. Solrizing all the objects in your repository:

In order to solrize all the objects in your repository, run:

solrizer.solrize_objects

h3. Advanced Usage

Solrizer-fedora inspects your repository objects and attempts to match your objects to your ruby models based on the hasModel declarations in the RELS-EXT datastream.

Go to the fedora admin interface (http://FEDORA_BASE_URL/fedora/admin) and create a new object with an PID of "changeme:123" and whatever Label you want.

Once you have created that object you will need to add the RELS-EXT datastream to it. Make the datastream ID "RELS-EXT", MIME-Type of "application/rdf+xml", and put the XML below in the XML from text field.

Solrizer-fedora will check to see if you have a matching ruby model called MyObject. If you do, it will load it and add any specific solr fields specified. So, assuming the following model:

class MyObject < ActiveFedora::Base

  has_metadata :name => "properties", :type=> ActiveFedora::MetadataDatastream do |m|
    m.field 'foo', :string
  end

end

Now add another datastream to the changeme:123 object and give it a datastream ID of "properties", a MIME-Type of "text/xml", and add the following to the XML from text field:

  bar

If you still have your fedora-solrizer class from above you can now solrize the object by ID:

solrizer.solrize "changeme:123"  

Now your solr doc with the "changeme:123" ID will include the following:

  bar

h3. Rake tasks

h4. solrizer:fedora:solrize

Required Argument:

• PID=ns:123 The pid of the object to index

Optional Arguments:

• FULL_TEXT=true does a full text index

h4. solrizer:fedora:solrize_objects

Optional Arguments:

• FULL_TEXT=true does a full text index
• INDEX_LIST=filename.csv indexes only the pids in the csv file

h2. Modifying and Testing the Solrizer-Fedora gem

In order to run the RSpec tests, it is necessary to have a hydra-jetty instance running. This can be accomplished two ways:

h3. Using the bundled jetty instance:

Configure the bundled hydra-jetty instance.

git submodule init
git submodule update

Once you have updated the jetty submodule, you can easily run the rspec tests with the following rake task:

rake hudson

While the primary intention of this task is to provide test coverage and documentation out on projecthydra's "continuous integration server":http://hudson.projecthydra.org, it can also be used locally to run tests without having to install and configure an instance of "hydra-jetty":https://github.com/projecthydra/hydra-jetty.

Note: if you have another instance of hydra-jetty running, you should either close it down prior to running the rake hudson task.

h3. Using a different instance of hydra-jetty:

If you prefer, you can run the specs against a different hydra-jetty instance. Follow the instructions included with those projects to start the jetty instance.

h2. Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so it doesn't get broken unintentionally in a future version.
• Commit, do not mess with rake file, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

h2. Copyright

Copyright (c) 2010 Matt Zumwalt and MediaShelf. See LICENSE for details.