active-fedora 2.3.0 → 2.3.1

data/CONSOLE_GETTING_STARTED.textile

@@ -1,25 +1,27 @@
+The concepts covered in this tutorial can be applied in any application with the active-fedora gem installed. (Don't forget to "require 'active-fedora'").
+
 h2. Dependencies
 
 You will need Ruby 1.8.7+ to go through this tutorial.  If you don't have Ruby 1.8.7 installed, "RVM":https://rvm.beginrescueend.com/ is the best way to install it.
 
 h2. Get a Copy of the Code
 
-All of the stuff you're learning here can be done in any application where you have the active-fedora gem installed and where you have called "require 'active-fedora'".  For this tutorial, you're cloning a full copy of the active-fedora code so you have access to the sample files that are stored there.
+It is probably easiest to Because this tutorial uses the sample files included   For this tutorial, you're cloning a full copy of the active-fedora code so you have access to the sample files that are stored there.
 
-First, clone the git repository and cd into the root
+First, clone the git repository and cd into the root:
 
 <pre>
 git clone git@github.com:mediashelf/active_fedora.git
 cd active_fedora
 </pre>
 
-If you don't have bundler installed yet, install it
+If you don't have bundler installed yet, install it:
 
 <pre>
 gem install bundler
 </pre>
 
-Now let bundler handle installing active-fedora's dependencies
+Now let bundler handle installing active-fedora's dependencies:
 
 <pre>
 bundle install
@@ -39,9 +41,9 @@ java -jar start.jar
 
 This will start Jetty and spit a bunch of info out onto the console.  Leave that terminal window open and open a new one to play around with ActiveFedora.
 
-You can also set up your own copies of Fedora and Solr to run against.   For info on that, see "Setting up Fedora and Solr for use with ActiveFedora":http://projects.mediashelf.us/projects/active-fedora/wiki/Setting_up_Fedora_and_Solr_for_use_with_ActiveFedora
+You can also set up your own copies of Fedora and Solr to run against.  For info on that, see "Setting up Fedora and Solr for use with ActiveFedora":http://projects.mediashelf.us/projects/active-fedora/wiki/Setting_up_Fedora_and_Solr_for_use_with_ActiveFedora
 
-h2. Open up the Console
+h2. Open up the (Rails) Console (or, use irb)
 
 <pre>
 script/console
@@ -55,7 +57,7 @@ require "active_fedora/samples" # these are the sample models and datastreams th
 
 h2. Initialize ActiveFedora
 
-In order to function, ActiveFedora needs to know where Fedora and Solr are running.  It gets this information from a YAML file.  
+In order to function, ActiveFedora needs to know where Fedora and Solr are running.  It gets this information from a YAML file.  You can see a sample fedora.yml in the ActiveFedora code on GitHub: "http://github.com/mediashelf/active_fedora/blob/master/config/fedora.yml":http://github.com/mediashelf/active_fedora/blob/master/config/fedora.yml
 
 <pre>
 ActiveFedora.init
@@ -71,19 +73,19 @@ I, [...]  INFO -- : FEDORA: initialized Fedora as: #<Fedora::Repository:0x102123
 
 As you can see, ActiveFedora.init defaults to using the fedora.yml included in the gem, which points to a local instance of jetty running on port 8983 with fedora and solr installed.
 
-If you want to use a different fedora.yml (pointing ActiveFedora to differed Fedora & Solr URLs), put your info into a new fedora.yml and pass that path to ActiveFedora.init
+If you want to use a different yml file, put your info (pointing ActiveFedora to specific Fedora & Solr URLs) into the file and pass its path to ActiveFedora.init:
 
 <pre>ActiveFedora.init("path/to/fedora.yml")</pre>
 
-You can see a sample fedora.yml in the ActiveFedora code on GitHub: "http://github.com/mediashelf/active_fedora/blob/master/config/fedora.yml":http://github.com/mediashelf/active_fedora/blob/master/config/fedora.yml
+h4. ActiveFedora within Rails
 
-If you are running a rails app, ActiveFedora.init will automatically look for configs in config/fedora.yml
+If you are running a rails app, ActiveFedora.init will automatically look for config/fedora.yml
 
 Also, within a rails app, you should create a file in config/initializers (ie. fedora_config.rb) that calls ActiveFedora.init
 
-h2. Load a fixture object to play with
+h2. Load a Fixture Object To Play With
 
-The ActiveFedora code includes foxml files for Fedora objects that you can load into a Fedora repository and play around with.  Here we will load the one called hydrangea_fixture_mods_article1.foxml.xml
+The ActiveFedora code includes sample Fedora objects (as foxml files) that you can load into a Fedora repository and play around with.  Here we will load the one called hydrangea_fixture_mods_article1.foxml.xml:
 
 <pre>
 filename = File.join(File.dirname(__FILE__),"spec","fixtures", "hydrangea_fixture_mods_article1.foxml.xml")
@@ -104,83 +106,106 @@ The easiest way to delete an object from Fedora is to use the following line.  N
 </pre>
 
 
-To see a more complete implementation of importing and deleting Fedora objects, see the code in the fedora rake tasks "https://github.com/mediashelf/active_fedora/blob/master/lib/tasks/fedora.rake":https://github.com/mediashelf/active_fedora/blob/master/lib/tasks/fedora.rake
+To see a more complete implementation of importing and deleting Fedora objects, see the code in this gem's fedora rake tasks "https://github.com/mediashelf/active_fedora/blob/master/lib/tasks/fedora.rake":https://github.com/mediashelf/active_fedora/blob/master/lib/tasks/fedora.rake
 
 
 *When you're done playing around with importing and deleting, make sure that you leave a copy of hydrangea:fixture_mods_article1 in fedora so we can play with it.*
 
 
-h4. Define a Model
-
-Look at the SpecialThing model defined in lib/active_fedora/samples/special_thing.rb to see how you declare an ActiveFedora model
+h3. Define a Model for Your (Active)Fedora Objects
 
+Look at the SpecialThing model defined in lib/active_fedora/samples/special_thing.rb to see how you declare an ActiveFedora model.
 
-Create an instance of the SpecialThing class
+Create an instance of the SpecialThing class:
 
 <pre>
 newthing = SpecialThing.new
 </pre>
 
-Get the pid of your new object
+Get the pid of your new object:
 
 <pre>
 newthing.pid
 => "changeme:30"
 </pre>
 
-This pid was retrieved from Fedora's getNextPid method.  Your object will not show up in Fedora until you save it using newthing.save, but let's hold off on saving it for now.
+This pid was retrieved from Fedora's getNextPid method.  
+
+Your object will not show up in the actual Fedora repository until you save it using newthing.save, but let's hold off on saving it for now.
 
-h3. RELATIONSHIPS
+h3. Fedora RELATIONSHIPS in ActiveFedora
 
-ActiveFedora provides convenience methods for creating and editing RELS-EXT relationships.  It also auto-generates methods for using Solr to search based on these relationships.
+ActiveFedora provides convenience methods for creating and editing Fedora RELS-EXT relationships.  It also auto-generates methods for searching these relationships with Solr. (see https://github.com/projecthydra/solrizer and https://github.com/projecthydra/solrizer-fedora)
 
-List the object's relationships.
+Use the relationships method to list the object's relationships:
 
 <pre>
 newthing.relationships
 => {:self=>{}}
 </pre>
 
-Call the "inspirations" method that was created by the has_relationship line in your class definition.
+The SpecialThing class definition contains these lines:
+
+<pre>
+  #
+  # RELATIONSHIPS
+  #
+  
+  # This is an example of how you can add a custom relationship to a model
+  # This will allow you to call .derivations on instances of the model to get a list of all of the _outbound_ "hasDerivation" relationships in the RELS-EXT datastream
+  has_relationship "derivations", :has_derivation
+
+  # This will allow you to call .inspirations on instances of the model to get a list of all of the objects that assert "hasDerivation" relationships pointing at this object
+  has_relationship "inspirations", :has_derivation, :inbound => true  
+</pre>
+
+ActiveFedora creates methods for the SpecialThing object based on has_relationship lines.  So we can call the "inspirations" method that is automatically created by ActiveFedora:
 
 <pre>
 newthing.inspirations
 => []
 </pre>
 
-Now create another Fedora object and make it assert that it's a part of the SpecialThing object, then save it to Fedora.
+This method is actually making a search request to Solr -- it is looking in Solr to see if the "newthing" object has any "inspirations" relationships.
+
+Now we'll create another Fedora object (using the default ActiveFedora object model) and we'll use ActiveFedora's add_relationship method to relate our new object to the SpecialThing objectl  We'll also save our new object in our Fedora repository.
 
 <pre>
-inspirational = ActiveFedora::Base.new
-inspirational.add_relationship(:has_derivation, newthing)
+newobj = ActiveFedora::Base.new
+newobj.add_relationship(:has_derivation, newthing)
 => true
-inspirational.relationships
+newobj.relationships
 => {:self=>{:has_derivation=>["info:fedora/changeme:30"]}}
-inspirational.save
+newobj.save
 => ...
-inspirational.pid
+newobj.pid
 => "changeme:164" # this is the pid you want to put in the following URLs as a replacement for {PID}
 </pre>
 
-You can now see that object in Fedora by going to http://localhost:8983/fedora/objects/{PID} and you can see the relationship asserted in http://localhost: 8983/fedora/objects/{PID}/datastreams/RELS-EXT/content
+You can see objects in Fedora by going to http://localhost:8983/fedora/objects/{PID} and you can see the relationships for an object by looking at the RELS-EXT datastream content:  http://localhost: 8983/fedora/objects/{PID}/datastreams/RELS-EXT/content
 
-Now look and see that the object you created shows up associated with newthing
+Now let's see if the "newthing" object has an "inspiration" relationship with our "newobj"
 
 <pre>
 newthing.inspirations
-=> ...
+=> ... (FIXME: put expected output here)
 newthing.inspirations.each {|pt| puts pt.pid }
-=> ...
+=> ... (FIXME: put expected output here)
 newthing.inspirations(:response_format=>:id_array)
-=> ...
+=> ... (FIXME: put expected output here)
 </pre>
 
-Note that you didn't have to save newthing in order for this relationship to show up in solr because it is an inbound relationship.  Only the object that makes the assertion needs to be saved in order for the search to work. In this case, the inspirational object asserts :has_derivation rather than the derivative asserting :is_derivation_of, so only the inspirational object had to be saved. 
+Note that you didn't have to save the "newthing" object in order for this relationship to show up in Solr because it is an inbound relationship. 
+
+Only the ActiveFedora object making the assertion needs to be saved in order for the search to work.  In our example above, new_obj asserts :has_derivation (rather than the derivative asserting :is_derivation_of), so only new_obj had to be saved. 
+
 
-h3. DATASTREAMS & METADATA
+h3. Fedora DATASTREAMS & METADATA in ActiveFedora
 
 h4. Blobs (a.k.a. File Datastreams, a.k.a Managed Content Datastreams)
 
+Here we create a simple Datastream (using the default Datastream model). 
+
 <pre>
 file = File.new('spec/fixtures/minivan.jpg')
 => #<File:spec/fixtures/minivan.jpg>
@@ -192,12 +217,12 @@ newthing.save
 => true
 </pre>
 
-Now user your browser to find the file datastreams in Fedora ...
+Now use your browser to find the file datastreams in Fedora ...
 
 
-h4. On auto-generating datatsream ids
+h4. On auto-generating datastream ids
 
-If you don't specify a dsid, ActiveFedora will generate one for you.
+If you don't specify a dsid, ActiveFedora will generate one for you.  In the example below, "DS1" is the dsID assigned to the new datastream
 
 <pre>
 file_ds2 = ActiveFedora::Datastream.new(:dsLabel => 'Minivan Plays', :altIDs => 'default', :controlGroup => 'M', :blob => file)
@@ -219,9 +244,11 @@ newthing.datastreams.keys
 newthing.save
 </pre>
 
-h2. Retrieving Existing Objects
+h2. Getting Existing Fedora Repository Objects 
+
+When you want your code to interact with existing digital objects in a Fedora repository, use the ActiveFedora load_instance method.
 
-You can use the load_instance class method on any kind of ActiveFedora::Base class to load objects from Fedora.
+You can use the load_instance class method on any kind of ActiveFedora::Base class to load objects from Fedora.  In the example below, the ActiveFedora object model for "copy_as_base" is ActiveFedora::Base.
 
 <pre>
 newthing.pid
@@ -229,20 +256,24 @@ newthing.pid
 copy_as_base = ActiveFedora::Base.load_instance("changeme:30")
 copy_as_base.pid
 => "changeme:30"
+newthing.relationships
+=> {:self=>{:has_model=>["info:fedora/afmodel:SpecialThing"]}} 
 copy_as_base.relationships
 => {:self=>{:has_model=>["info:fedora/afmodel:SpecialThing"]}} 
+newthing.datastreams.keys
+=> ["DS1", "descMetadata", "Foo1", "minivan", "RELS-EXT", "rightsMetadata", "DC", "extraMetadataForFun"] 
 copy_as_base.datastreams.keys
 => ["DS1", "descMetadata", "Foo1", "minivan", "RELS-EXT", "rightsMetadata", "DC", "extraMetadataForFun"] 
 </pre>
 
-As you can see, ActiveFedora::Base will load the object, its datastreams, its generic Fedora Object information, and even its RELS-EXT relationships.  It will _not_, however, know how to deserialize any model-specific metadata datastreams.  In other words, ActiveFedora::Base treats all datastreams as generic Fedora datastreams.
+As you can see, ActiveFedora::Base will load the object, its datastreams, its generic Fedora Object information, and even its RELS-EXT relationships.  It will _not_, however, know how to deserialize any model-specific metadata datastreams.  In other words, *ActiveFedora::Base treats all datastreams as generic Fedora datastreams*.
 
 <pre>
 copy_as_base.datastreams["extraMetadataForFun"].class
 => ActiveFedora::Datastream
 </pre>
 
-If you want the model-specific metadata to be deserialized, you must call load_instance on the appropriate model class.  This will load all of the same info as ActiveFedora::Base, but it will also attempt to deserialize the xml from any metadata datastreams that were declared by the has_metadata method in the model.
+If you want the model-specific metadata to be deserialized, you must call load_instance on the appropriate ActiveFedora model class.  This will load all of the same info as ActiveFedora::Base, but it will also attempt to deserialize the xml from any metadata datastreams that were declared by the has_metadata method in the model.
 
 <pre>
 copy_as_specialthing = SpecialThing.load_instance(newthing.pid)
@@ -252,13 +283,22 @@ copy_as_specialthing.datastreams["extraMetadataForFun"].class
 => ActiveFedora::Marpa::DcDatastream
 </pre>
 
-h2. Finding Objects
 
-All descendants of ActiveFedora::Base provide a find method that will search for objects of the given class.  The method is somewhat incomplete at the moment, but is functional.  We are actively working on making it better.
+You can use "find" instead of "load_instance".  In practice, we tend to use load_instance though -- it's more direct.
+
+<pre>
+Base.find("changeme:30")
+SpecialThing.find("changeme:30")
+</pre>
+
+
+h3. Finding Fedora Repository Objects of the Same Class
+
+All descendants of the ActiveFedora::Base class inherit the "find" method which searches Solr for Fedora repository objects of the given class.  The method is somewhat incomplete at the moment, but is functional.  We are actively working on making it better.
 
 h3. Finding Instances of the Class
 
-Imitating ActiveRecord, you can search for instances of the given class by calling find(:all) on that class.  In current versions of the gem, this method searches solr using the active_fedora_model_field.  In future versions it will not hit solr at all, instead relying on Fedora's Resource Index and searching for anything that asserts "conformsTo" or "hasModel" relationships pointing at the given model.
+Imitating ActiveRecord, the find(:all) method (inherited from the ActiveFedora::Base class) searches for instances of the calling class.  In current versions of the gem, this method searches solr using the active_fedora_model_field.  In future versions it will not hit solr at all, instead relying on Fedora's Resource Index and searching for anything that asserts "conformsTo" or "hasModel" relationships pointing at the given model.
 
 <pre>
 ActiveFedora::Base.find(:all)
@@ -273,21 +313,12 @@ solr_result = ActiveFedora::SolrService.instance.conn.query('has_model_s:info\:f
 
 This query will return a Solr::Result containing all of the objects that have conformsTo relationships pointing at info:fedora/afmodel:SpecialThing in their RELS-EXT.  This relationship gets added to the RELS-EXT whenever you save an object as a given ActiveFedora model and it does not get erased if you later save it as a different model.
 
-h3. Finding (Loading) a specific Object
 
-You can use this instead of .load_instance.  In practice, we tend to use load_instance though -- it's more direct.
-
-<pre>
-Base.find("changeme:30")
-SpecialThing.find("changeme:30")
-</pre>
-
-
-h3. Looking a bit deeper at what Models do
+h2. More About ActiveFedora Models
 
 ActiveFedora Models don't actually do much.  They mainly keep a list of datastream ids and associate them with classes that help you use the content from those datastreams.
 
-When you're ready to learn more about how to define ActiveFedora models and OM-based datastreams, open up the files in lib/active_fedora/samples.  Those will give you more background.  Here, we're seeing what happens when you use those Models and datastreams.
+When you're ready to learn more about how to define ActiveFedora models and OM-based datastreams, examine the files in lib/active_fedora/samples.  Those will give you more background.  Here, we're seeing what happens when you use those Models and datastreams.
 
 For now, load an instance of the SpecialThing model and take a look at its datastreams.
 
@@ -301,10 +332,12 @@ st.datastreams.keys
 
 We see the three datastreams that are declared by the SpecialThing Model, but where did the other datastreams come from?
 
+h3. Default Fedora Datastreams
+
 The RELS-EXT is where Fedora objects store their relationships, so SpecialThing uses that datastream when it uses the methods created by has_relationship.
 
-The other two datastreams, DC and properties, were already there in the object we imported.  Our model doesn't define anything about those datastreams, so they are loaded as mere ActiveFedora::Datastreams.  When a datastream is loaded in this way, you can still see it and access/update its content as a blob, but your model doesn't know anything special about its contents.  This behavior is what allows us to have multiple interfaces for the same content.  One model might care only about the descMetadata and the properties while another model only cares about the descMetadata and rightsMetadata.  The two models only need to be consistent with each other when they are both operating on the same datastream. 
- 
+The other two datastreams, DC and properties, were already there in the object we imported.  Our model doesn't define anything about those datastreams, so they are loaded as mere ActiveFedora::Datastreams.  When a datastream is loaded in this way, you can still see it and access/update its content as a blob, but your model doesn't know anything special about its contents.  This behavior is what allows us to have multiple interfaces for the same content.  One model might care only about the descMetadata and the properties while another model only cares about the descMetadata and rightsMetadata.  The two models only need to be consistent with each other when they are both operating on the same datastream in the same object.
+
 Let's see what classes the datastreams have been bound to
 
 <pre>

data/Gemfile.lock

@@ -1,8 +1,7 @@
 PATH
   remote: .
   specs:
-    active-fedora (2.2.0.rails3pre1)
-      active-fedora
+    active-fedora (2.3.1)
       activeresource
       equivalent-xml
       facets

data/README.textile

@@ -1,6 +1,6 @@
 h2. Description
 
-RubyFedora and ActiveFedora provide a set of Ruby gems for creating and managing objects in the Fedora Repository Architecture ("http://fedora-commons.org":http://fedora-commons.org).
+RubyFedora and ActiveFedora provide a set of Ruby gems for creating and managing objects in the Fedora Repository Architecture ("http://fedora-commons.org":http://fedora-commons.org).  ActiveFedora is loosely based on "ActiveRecord" in Rails.
 
 h2. Getting Help
 
@@ -18,7 +18,7 @@ h2. Getting Started
 
 The "ActiveFedora Console Tour":https://github.com/mediashelf/active_fedora/blob/master/CONSOLE_GETTING_STARTED.textile  gives you a brief tour through ActiveFedora's features on the command line.
 
-h2. Testing
+h2. Testing (this Gem)
 
 In order to run the RSpec tests, you need to have a copy of the ActiveFedora source code, and then run bundle install in the source directory.
 

data/config/fedora.yml

@@ -7,7 +7,7 @@ test:
   fedora:
     url: http://fedoraAdmin:fedoraAdmin@127.0.0.1:8983/fedora
   solr:
-    url: http://127.0.0.1:8983/solr/development
+    url: http://127.0.0.1:8983/solr/test
 production:
   fedora:
     url: http://fedoraAdmin:fedoraAdmin@127.0.0.1:8080/fedora

data/config/predicate_mappings.yml

@@ -13,34 +13,31 @@
 # With the last two lines of this file uncommented, the relationships hash of your object will include:
 #   :oai_item_id => ["info:fedora/oai:example.edu:changeme:500"]
 #
-# With the last two lines of this file commented out, the relationships hash of your object will include:
-#   "oai_itemID" => ["info:fedora/oai:example.edu:changeme:500"]
-#   
 :predicate_mapping:
   info:fedora/fedora-system:def/relations-external#: 
-    :is_derivation_of: isDerivationOf
-    :is_metadata_for: isMetadataFor
-    :is_member_of_collection: isMemberOfCollection
-    :has_derivation: hasDerivation
-    :is_annotation_of: isAnnotationOf
-    :is_constituent_of: isConstituentOf
-    :is_dependent_of: isDependentOf
-    :has_collection_member: hasCollectionMember
+    :conforms_to: conformsTo
     :has_annotation: hasAnnotation
+    :has_collection_member: hasCollectionMember
     :has_constituent: hasConstituent
     :has_dependent: hasDependent
-    :is_part_of: isPartOf
+    :has_derivation: hasDerivation
+    :has_description: hasDescription
     :has_equivalent: hasEquivalent
-    :is_subset_of: isSubsetOf
-    :is_description_of: isDescriptionOf
-    :is_member_of: isMemberOf
-    :has_model: hasModel
-    :conforms_to: conformsTo
     :has_metadata: hasMetadata
-    :has_subset: hasSubset
-    :has_description: hasDescription
-    :has_part: hasPart
     :has_member: hasMember
+    :has_model: hasModel
+    :has_part: hasPart
+    :has_subset: hasSubset
+    :is_annotation_of: isAnnotationOf
+    :is_constituent_of: isConstituentOf
+    :is_dependent_of: isDependentOf
+    :is_derivation_of: isDerivationOf
+    :is_description_of: isDescriptionOf
+    :is_member_of: isMemberOf
+    :is_member_of_collection: isMemberOfCollection
+    :is_metadata_for: isMetadataFor
+    :is_part_of: isPartOf
+    :is_subset_of: isSubsetOf
   info:fedora/fedora-system:def/model#:
     :has_model: hasModel
 #  http://www.openarchives.org/OAI/2.0/: 

data/lib/active_fedora.rb

@@ -3,7 +3,6 @@ gem 'solr-ruby'
 require "loggable"
 
 $: << 'lib'
-require 'logger'
 require 'active_fedora/solr_service.rb'
 require "solrizer"
 
@@ -30,6 +29,8 @@ ENABLE_SOLR_UPDATES = true unless defined?(ENABLE_SOLR_UPDATES)
 
 module ActiveFedora #:nodoc:
   
+  include Loggable
+  
   class << self
     attr_accessor :solr_config, :fedora_config
   end
@@ -90,10 +91,6 @@ module ActiveFedora #:nodoc:
     Fedora::Repository.instance
   end
 
-  def self.logger      
-    @logger ||= defined?(RAILS_DEFAULT_LOGGER) ? RAILS_DEFAULT_LOGGER : Logger.new(STDOUT)
-  end
-
   def self.predicate_config
     @predicate_config_path ||= build_predicate_config_path
   end

data/lib/active_fedora/samples/hydra-mods_article_datastream.rb

@@ -1,11 +1,11 @@
 require "active-fedora"
 module Hydra
   
-  # This is an example of a NokogiriDatastream that defines a terminology for MODS xml
+  # This is an example of a NokogiriDatastream that defines an OM terminology for MODS xml
   # It focuses on the aspects of MODS that deal with descriptive metadata for published articles
-  # The real version of this Terminology is part of the hydra-head plugin.  See https://github.com/projecthydra/hydra-head/blob/master/lib/hydra/mods_article.rb
+  # This is not the hydra-head plugin version of this OM Terminology; See https://github.com/projecthydra/hydra-head/blob/master/lib/hydra/mods_article.rb
   #
-  # Things to note about the Terminology it defines:
+  # Things to note about the OM Terminology defined here:
   #
   # * Uses :ref terms to repeat the structures of a mods:name with a different @type on the mods:name element
   # * Defines a term lang_code that maps to "languageTerm[@type=code]"