hydra 10.0.0 → 10.0.1

data/doc/Lesson:-build-a-book-model.md

@@ -1,265 +0,0 @@
-# Goals
-* Define a simple OM (Opinionated Metadata) Terminology for Book Metadata that we will track as XML Datastreams
-* Start the Rails console and run code interactively in the console
-* Create Datastream objects that use your OM Terminology
-* Define an ActiveFedora Model for Book objects 
-* Declare a Datastream called descMetadata on your Book model and make it use your Book Metadata Terminology
-* Delegate methods from Book objects to their descMetadata Datastream
-* Create Book objects that use your Book Model
-* See how an object has been indexed into Solr
-* See how & where objects and metadata are stored in Fedora
-* Use OM to Manage how your Metadata is indexed in Solr
-* Re-index objects into Solr (update Solr based on any changes to an object, its Model, or the OM Terminologies it uses)
-
-# Explanation
-In Fedora an object can have many 'datastreams' which are either content for the object or metadata about the object. We are going to create a 'book' object.  This object will have a metadata datastream which will contain some XML that describes the properties of the book.  We'll call this datastream 'descMetadata'.  You are free to call it whatever you like, but 'descMetadata' is a loose convention that stands for 'descriptive metadata'.
-
-Once you've created an object and saved it in Fedora, you also want to be able to search for it in Solr.  ActiveFedora and OM make it easy to get your metadata into Solr and manage if/when/how your metadata is indexed. 
-
-# Steps
-
-### Step 1: Create an OM Terminology for Book Metadata
-
-First we'll create a Ruby class that represents this descriptive metadata.  Make a new directory for our datastreams by typing in 
-```bash
-$> mkdir app/models/datastreams
-```
-
-Now we'll create a file called `app/models/datastreams/book_metadata.rb`
-
-Paste the following code into that file:
-
-```ruby
-class BookMetadata < ActiveFedora::OmDatastream
-
-  set_terminology do |t|
-    t.root(path: "fields")
-    t.title
-    t.author
-  end
-
-  def self.xml_template
-    Nokogiri::XML.parse("<fields/>")
-  end
-
-  def prefix
-    # set a datastream prefix if you need to namespace terms that might occur in multiple data streams 
-    ""
-  end
-
-end
-```
-
-This class extends from OmDatastream. OM is a gem that allows us to describe the format of an xml file and access properties. We are using OM by calling the `set_terminology` method.  The xml_template method tells OM how to create a new xml document for this class. 
-
-**Tip:** If you want to learn about OM Terminologies and how they work, visit the [Tame your XML with OM](https://github.com/projecthydra/om/wiki/Tame-your-XML-with-OM) Tutorial.
-
-### Step 2: Start the Rails console
-
-Let's take a look at how this class works.  We'll start the rails console by typing 
-
-```bash
-$> rails console
-```
-
-You should see something like `Loading development environment (Rails 3.2.11)`.  Now you're in a "[REPL](http://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)", or *interactive ruby console* that has all of your Rails application's code and configuration loaded. 
-
-### Step 3: In the console, create Datastream objects that use your OM Terminology
-
-Let's create a new BookMetadata instance. I've shown the expected output after each command:
-
-```text
-d = BookMetadata.new
- => #<BookMetadata @pid="" @dsid="" @controlGroup="X" changed="false" @mimeType="text/xml" > 
-d.title = "ZOIA! Memoirs of Zoia Horn, Battler for the People's Right to Know."
- => "ZOIA! Memoirs of Zoia Horn, Battler for the People's Right to Know." 
-d.author = "Horn, Zoia"
- => "Horn, Zoia" 
-d.to_xml
- => "<fields>\n  <title>ZOIA! Memoirs of Zoia Horn, Battler for the People's Right to Know.</title>\n  <author>Horn, Zoia</author>\n</fields>"
-```
-
-Once you're done, exit the console by typing ```exit```
-
-
-### Step 4: Define a Book Model
-
-Now let's, create a model that uses this datastream.  Create a new file at `app/models/book.rb`. We'll paste in this code:
-
-```ruby
-class Book < ActiveFedora::Base
-  has_metadata 'descMetadata', type: BookMetadata
-
-  has_attributes :title, datastream: 'descMetadata', multiple: false
-  has_attributes :author, datastream: 'descMetadata', multiple: false
-
-end
-```
-
-We've defined our Book model to use the BookMetadata for its datastream called 'descMetadata'.  We're telling the model to use the descMetadata as the delegate for the properties 'title' and 'author'.  We are also telling Active Fedora to treat these attributes as single values rather than as multi-valued arrays.
-
-### Step 5: In the console, create Datastream objects that use your OM Terminology
-
-Now we'll open the `rails console` again and see how to work with our book.
-
-```text
-b = Book.create(title: 'Anna Karenina', author: 'Tolstoy, Leo')
- => #<Book pid:"changeme:1", title:["Anna Karenina"], author:["Tolstoy, Leo"]> 
-```
-
-We've created a new Book object in the repository.  You can see that it has a pid (Fedora Commons persistence identifier) of 'changeme:1'.  Because you set title and author to delegate to the descMetadata datastream, they are stored in that datastream's XML and can be accessed either through the delegated methods on the Book, or by going specifically to the datastream. 
-
-
-```text
-b.descMetadata
- => #<BookMetadata @pid="changeme:1" @dsid="descMetadata" @controlGroup="M" changed="false" @mimeType="text/xml" > 
-b.title
- => "Anna Karenina" 
-b.author
- => "Tolstoy, Leo"
-b.descMetadata.title
- => ["Anna Karenina"] 
-b.descMetadata.author
- => ["Tolstoy, Leo"] 
-```
-
-
-### Step 6: See what your Book objects look like in Fedora and Solr
-
-If we go to [[http://localhost:8983/fedora/objects/changeme:1]] we should see what it looks like in fedora.  Note especially that the xml datastream has been ingested [[http://localhost:8983/fedora/objects/changeme:1/datastreams/descMetadata/content]].  The content of that datastream should look like this in your browser:
-
-```xml
-<fields>
-  <title>Anna Karenina</title>
-  <author>Tolstoy, Leo</author>
-</fields>
-```
-
-Let's also see that this book has been ingested into the Solr search index. [[http://localhost:8983/solr/select?q=changeme:1]].  It should look like the sample below.  Note that, at this point, the title and author have not been stored in solr.  You only get fields like `system_create_dtsi`, `system_modified_dtsi`, `id`, `object_profile_ssm`, and `has_model_ssim`.  In the next step we will modify our BookMetadata datastream to add the book metadata to the solr document.
-
-```xml
-<?xml version="1.0"?>
-<response>
-  <lst name="responseHeader">
-    <int name="status">0</int>
-    <int name="QTime">3</int>
-    <lst name="params">
-      <str name="q">changeme:4</str>
-    </lst>
-  </lst>
-  <result name="response" numFound="1" start="0" maxScore="0.05991731">
-    <doc>
-      <date name="system_create_dtsi">2013-05-06T16:22:39Z</date>
-      <date name="system_modified_dtsi">2013-05-06T16:22:39Z</date>
-      <arr name="active_fedora_model_ssim">
-        <str>Book</str>
-      </arr>
-      <str name="id">changeme:4</str>
-      <arr name="object_profile_ssm">
-        <str>{"datastreams":{"RELS-EXT":{"dsLabel":"Fedora Object-to-Object Relationship Metadata","dsVersionID":"RELS-EXT.0","dsCreateDate":"2013-05-06T16:22:40Z","dsState":"A","dsMIME":"application/rdf+xml","dsFormatURI":null,"dsControlGroup":"X","dsSize":277,"dsVersionable":true,"dsInfoType":null,"dsLocation":"changeme:4+RELS-EXT+RELS-EXT.0","dsLocationType":null,"dsChecksumType":"DISABLED","dsChecksum":"none"},"descMetadata":{"dsLabel":null,"dsVersionID":"descMetadata.0","dsCreateDate":"2013-05-06T16:22:41Z","dsState":"A","dsMIME":"text/xml","dsFormatURI":null,"dsControlGroup":"M","dsSize":81,"dsVersionable":true,"dsInfoType":null,"dsLocation":"changeme:4+descMetadata+descMetadata.0","dsLocationType":"INTERNAL_ID","dsChecksumType":"DISABLED","dsChecksum":"none"},"rightsMetadata":{}},"objLabel":null,"objOwnerId":"fedoraAdmin","objModels":["info:fedora/fedora-system:FedoraObject-3.0"],"objCreateDate":"2013-05-06T16:22:39Z","objLastModDate":"2013-05-06T16:22:39Z","objDissIndexViewURL":"http://localhost:8983/fedora/objects/changeme%3A4/methods/fedora-system%3A3/viewMethodIndex","objItemIndexViewURL":"http://localhost:8983/fedora/objects/changeme%3A4/methods/fedora-system%3A3/viewItemIndex","objState":"A"}</str>
-      </arr>
-      <arr name="has_model_ssim">
-        <str>info:fedora/afmodel:Book</str>
-      </arr>
-      <date name="timestamp">2013-05-06T16:22:58.397Z</date>
-      <float name="score">0.05991731</float>
-    </doc>
-  </result>
-  <lst name="facet_counts">
-    <lst name="facet_queries"/>
-    <lst name="facet_fields">
-      <lst name="active_fedora_model_ssi"/>
-      <lst name="object_type_si"/>
-    </lst>
-    <lst name="facet_dates"/>
-    <lst name="facet_ranges"/>
-  </lst>
-</response>
-```
-### Step 7: See how your Book metadata are indexed into Solr
-
-
-The to_solr method is what generates the solr document for your objects and their datastreams.  To see the full solr document for the book we created, call
-
-```text
-b.to_solr
-```
-
-To see just the part of the solr document that comes from the descMetadata datastream (which has our book title and author), call
-
-```text
-b.descMetadata.to_solr
- => {} 
-```
-
-As you can see, the descMetadata datastream is returning an empty Hash, meaning that it isn't indexing the author and title values.
-
-### Step 8: Change how your Book metadata are indexed into Solr
-
-To make the BookMetadata Terminology index the author and title fields, you need to reopen `app/models/datastreams/book_metadata.rb` and change the terminology section to look like this:
-
-```ruby
-  set_terminology do |t|
-    t.root(path: "fields")
-    t.title(index_as: :stored_searchable)
-    t.author(index_as: :stored_searchable)
-  end
-```
-
-**Note:** Because we have made changes to our Ruby code that we want to use, we need to restart the Rails console so that it will reload all of the code, including our latest changes.
-
-Now, **restart the rails console** and we can load the object we previously created:
-
-```text
-b = Book.find('changeme:1')
- => #<Book pid:"changeme:1", title:"Anna Karenina", author:"Tolstoy, Leo">
-```
-
-Check and see that to_solr includes the title and author fields.
-
-```text
-b.descMetadata.to_solr
- => {"title_tesim"=>["Anna Karenina"], "author_tesim"=>["Tolstoy, Leo"]} 
-```
-Now when you call `.to_solr` on a BookMetadata datastream it returns a solr document with fields named `title_tesim` and `author_tesim` that contain your title and author values.  Those are the field names that we will add to Blacklight's queries in [[Lesson: Make Blacklight Return Search Results]].
-
-
-### Step 9: Re-index an object in Solr
-
-Now we'll call the ```update_index``` method, which republishes the Solr document using the changes we've made.
-
-```text
-b.update_index
- => {"responseHeader"=>{"status"=>0, "QTime"=>25}} 
-```
-
-If you refresh the document result from solr ([[http://localhost:8983/solr/select?q=changeme:1]]) you should see that these fields have been added to the solr_document:
-
-```xml
-<arr name="title_tesim">
-    <str>Anna Karenina</str>
-</arr>
-<arr name="author_tesim">
-    <str>Tolstoy, Leo</str>
-</arr>
-```
-
-**Aside:** The strange suffixes on the field names are provided by [solrizer](http://github.com/projecthydra/solrizer). You can read about them in the [solrizer documentaton](https://github.com/projecthydra/hydra-head/wiki/Solr-Schema). In short, the **_tesim** suffix tells Solr to treat the values as _**t**ext_ in the _**e**nglish_ language that should be _**s**tored_, _**i**ndexed_ and allowed to be _**m**ultivalued_. This _tesim suffix is a useful catch-all that gets your searches working predictably with minimal fuss. As you encounter cases where you need to index your content in more nuanced ways, there are ways to change these suffixes in order to achieve different results in Solr.
-
-#### Why doesn't the Book show up in Blacklight?
-
-Now your object is indexed properly, but it **won't show up in Blacklight's search results** until you've turned off access controls and added the appropriate fields to Blacklight's queries.  We cover those in the next 2 lessons.
-
-### Step 10: Commit your changes
-
-Now that we've got our model working, it's a great time to commit to git:
-
-```text
-git add .
-git commit -m "Created a book model and a datastream"
-```
-
-# Next Step
-Go on to [[Lesson: Make Blacklight Return Search Results]] or return to the [[Dive into Hydra]] page.
-
-If you want to learn about OM Terminologies and how they work, visit the [Tame your XML with OM](https://github.com/projecthydra/om/wiki/Tame-your-XML-with-OM) Tutorial.

data/doc/Lesson:-install-hydra-jetty.md

@@ -1,148 +0,0 @@
-# Goals
-* Install a copy of hydra-jetty, which includes pre-configured copies of Fedora and Solr
-* Learn to start and stop hydra-jetty (which contains Fedora and Solr)
-
-# Explanation
-In order to use blacklight and hydra-head, you need an installation of Solr.  In addition, hydra-head requires a copy of Fedora.  Fedora and Solr are both Java web applications that need to run in a servlet container like Tomcat or Jetty. 
-
-For developer environments, we have created a package called hydra-jetty which provides both services pre-installed within a Jetty Java application server. Whenever you need Fedora and Solr running in your development environment, just start or stop that copy of hydra-jetty.
-
->
-**TIP** *DO NOT* use hydra-jetty for production installations.  The hydra-jetty passwords are well-known and the installation has not been secured for non-local use.
->
-
-# Steps
-
-### Step 1: Install the hydra-jetty package 
-
-Use the hydra:jetty generator to install the hydra-jetty package by running:
-
->
-**TIP** hydra-jetty is a very large download.  If you are completing this lesson as part of a workshop, the facilitator may have a copy of hydra-jetty that you can load from a flash-drive rather than downloading over the internet. The workshop facilitator will provide alternate instructions for this step.
->
-
-```text
-rails g hydra:jetty
-```
-
-Note: this requires that your system have curl installed. If it does not, you may see an unhelpful error:
-
-```text
-Unable to download jetty from https://github.com/projecthydra/hydra-jetty/archive/v7.0.0.zip
-```
-
-This generator is provided by the jettywrapper gem.
-
-
-This can be very slow (over 100Mb of download).  When it's done you'll see the directory named `jetty` has been created. If you run `git status` you will see 
-
-```text
-# On branch master
-# Untracked files:
-#   (use "git add <file>..." to include in what will be committed)
-#
-#	jetty/
-```
-
-**Windows Tip**:  Currently this rake task doesn't work on Windows (see [jettywrapper issue #14](https://github.com/projecthydra/jettywrapper/issues/14) for status).  Workaround: Download https://github.com/projecthydra/hydra-jetty/archive/v7.0.0.zip, unpack it, and move the unpacked 'jetty' directory to the root of your application.
-
-### Step 2: Make git ignore the jetty directory
-
-We want git to ignore the jetty directory for the same reasons that we don't check our development databases into git -- because it's big and bulky and you don't actually need other developers to have exact copies of your jetty as long as they have all the other code. 
-
-We do that by editing `.gitignore` and adding the something like this:
-
-```text
-# Ignore jetty directory (from hydra-jetty)
-/jetty
-
-```
-
-Now commit this change
-
-```text
-git add .gitignore
-git commit -m "Adds /jetty to .gitignore"
-```
-
-### Step 3: Start Jetty
-At the project root, type 
-
-```text
-rake jetty:start
-```
-
-You should see output like this:
-
->
-```text
-Starting jetty with these values: 
-jetty_home: /Users/justin/hydra-demo/jetty
-jetty_command: java -Djetty.port=8983 -Dsolr.solr.home=/Users/justin/hydra-demo/jetty/solr -Xmx256m -XX:MaxPermSize=128m -jar start.jar
-Logging jettywrapper stdout to /Users/justin/hydra-demo/jetty/jettywrapper.log
-Wrote pid file to /Users/justin/hydra-demo/tmp/pids/_Users_justin_hydra-demo_jetty.pid with value 8315
-Waited 5 seconds for jetty to start, but it is not yet listening on port 8983. Continuing anyway.
-Started jetty (5575.9ms)
-```
->
-
-hydra-jetty has a fair amount of stuff in it, so it may take up to a minute to start.  You can check to see if it's started by going to [[http://localhost:8983/solr]]
-
-If Fedora, Solr, or jetty itself are not starting, you'll want to look at the jettywrapper log to diagnose.
-
-**Windows Tip:** This rake task is not currently working on Windows (see [jettywrapper issue #13](https://github.com/projecthydra/jettywrapper/issues/13) for status).  In the meantime, start jetty manually
-
-```text
-cd jetty
-java -Djetty.port=8983 -Dsolr.solr.home=/Users/justin/hydra-demo/jetty/solr -Xmx256m -XX:MaxPermSize=128m -jar start.jar
-```
-
-### Step 4: Look at the jettywrapper log
-
-The jetty:start rake task runs jetty as a background job, so jetty's logs won't appear in your terminal.  Instead they're written to the file `jetty/jettywrapper.log`.  If you look at the output from running the jetty:start task, you'll see that one line gives you the full path to the file, for example:
-
-```text
-Logging jettywrapper stdout to /Users/justin/hydra-demo/jetty/jettywrapper.log
-```
-
-You can open this log file with any text editor or log reader.
-
-```text
-vi jetty/jettywrapper.log
-```
-
-### Step 5: Monitor the jettywrapper log
-
->
-**Tip:** if jetty is taking a long time to start, you can watch its output using the tail command with the path to your jettywrapper.log.  For example:
-
-```text
-tail -f jetty/jettywrapper.log
-```
->
-
-As Jetty, Fedora, and Solr start you will see more info being written to the log file. After a few moments you will be able to open jetty at [[http://localhost:8983]] or [[http://0.0.0.0:8983]] (**note:** The root page will give a 404 error, but should have three links to the applications running in Jetty: /solr, /fedora and /fedora-test)
-
-### Step 6: Stop Jetty
-You might have guessed this one.  In order to stop jetty, at the project root, type
-
-```text
-rake jetty:stop
-```
-
-### Step 7: Start Jetty again
-Before proceeding to the next lesson, make sure jetty is running.  If you're not sure whether it's running, go to http://localhost:8983.  If jetty is running a page will load.  If jetty is not running no page will load.
-
-If it's not running, just use the jetty:start rake task again.
-
-```text
-rake jetty:start
-```
-
-
->
-**Tip:** Sometimes people are confused about whether they need to restart jetty when they restart their Rails application.  In most cases it is fine to leave jetty running when you start, stop, and restart the Rails application.  The only exception is when you make changes to Solr's configuration or Fedora's configuration -- these would be changes to files inside of your copy of hydra-jetty (ie. jetty/solr/config), not changes to files in your Rails application's Ruby code.  In those cases, where you have made changes to Solr or Fedora's configuration, you need to restart Jetty in order for those changes to take effect.  The most common change that requires restarting jetty is when you modify the solrconfig.xml or schema.xml in your solr config directory.
->
-
-# Next Step
-Go on to [[Lesson: Start the Application & Search for Results]] or return to the [[Dive into Hydra]] page.

data/doc/Lesson:-make-blacklight-return-search-results.md

@@ -1,69 +0,0 @@
-# Goals
-* *(for now)* Turn off access controls for Blacklight-based searches and "show" views 
-* Tell Blacklight which fields to use in searches
-* Run a search in Blacklight and see results rendered
-
-# Explanation
-
-In [[Lesson: Build a Book Model]] you made a Book object, saved it, and saw that the Book's metadata was indexed in Solr.  Now we will make that Book appear in your Blacklight searches.
-
-One of the main features that Hydra adds to Blacklight is the ability to control who has access to which information in search results.  That topic gets a little bit complicated.  For the purpose of this Tutorial we want to stay focused on showing you how to set up an app, define models and create objects based on those models, so in order to keep things simple we will make this Hydra Head behave like an open access repository where everyone can see everything.  Once you've completed this tutorial, you can check out [Access Controls with Hydra](https://github.com/projecthydra/hydra-head/wiki/Access-Controls-with-Hydra) to learn how to assert access controls on objects and enforce those access controls in a Hydra Head.
-
-Once you've turned off access controls in step #1, we show you how to tell blacklight which fields you want to use for default searches in the remaining steps.
-
-# Steps
-
-### Step 1: Comment out the lines that enforce access controls in Blacklight's CatalogController
-
-If you open ```app/controllers/catalog_controller.rb``` and look at the code near lines 8-12 you should see this:
-```ruby
-  # These before_filters apply the hydra access controls
-  before_filter :enforce_show_permissions, :only=>:show
-  # This applies appropriate access controls to all solr queries
-  CatalogController.solr_search_params_logic += [:add_access_controls_to_solr_params]
-```
-
-This code tells blacklight to enforce access controls on the search and result view pages.  For the time being we will turn this off by commenting out two lines so that it looks like this:
-
-```ruby
-  # These before_filters apply the hydra access controls
-  #before_filter :enforce_show_permissions, :only=>:show
-  # This applies appropriate access controls to all solr queries
-  #CatalogController.solr_search_params_logic += [:add_access_controls_to_solr_params]
-```
-Then, save the file.
-
-### Step 2: Run a search in the CatalogController
-
-Visit or reload the page at [[http://localhost:3000/]].  You should see the Blacklight search interface with a search box.  If you search for 'Anna' you don't see any results even though we created a Book called "Anna Karenina" and indexed it in Solr in the last lesson.  
-
-### Step 3: Tell Blacklight which fields to use in Queries
-
-The reason why we're not getting any hits is because we haven't told Blacklight which fields to search in.  Let's fix that by setting the default 'qf' solr parameter.  Open `app/controllers/catalog_controller.rb` and set the `default_solr_params` section (around line 18) to this:
-
-```ruby
-    config.default_solr_params = { 
-      :qf => 'title_tesim author_tesim',
-      :qt => 'search',
-      :rows => 10 
-    }
-```
-
-### Step 4: Re-run your search
-
-Save the file, and refresh your web browser. You should now see a result for "Anna Karenina" when you search for "Anna"
-
-**Tip:** When you make changes like this, you *don't* need to restart the Rails server.  This is because in development mode (which is the default environment for the Rails server), the Rails server reloads any files in app/models, app/controllers, app/views, etc. for every request it receives from a browser.  This makes the server slower, but it makes life much smoother when you're actively developing and making changes.
-
-### Step 5: Commit your changes
-
-Now that we've updated our search functionality, it's a great time to commit to git:
-
-```text
-git add .
-git commit -m "Disabled access controls and set default search fields"
-```
-
-# Next Step
-Go on to **BONUS** [[Lesson: Define Relationships Between Objects]] or 
-explore other [Dive into Hydra](Dive into Hydra#Bonus) tutorial bonus lessons.