talia_core 0.5.4 → 0.7.0

data/lib/talia_core/active_source_parts/xml/source_builder.rb

@@ -27,13 +27,17 @@ module TaliaCore
       #     </source>
       #     ...
       #   </sources>
+      #
+      # Also see the parent class, TaliaUtil::Xml::BaseBuilder, for more information
       class SourceBuilder < TaliaUtil::Xml::BaseBuilder
         
+        # Builds the XML for a single source, and returns the result as
+        # a string
         def self.build_source(source)
           make_xml_string { |build| build.write_source(source) }
         end
         
-        # Builds the RDF for a single source
+        # Build the XML for a single source.
         def write_source(source)
           @builder.source do 
             source.attributes.each { |attrib, value| write_attribute(attrib, value) }
@@ -43,7 +47,7 @@ module TaliaCore
         
         private
         
-        # build an attribute entry in a source
+        # Builds an attribute tag (with contents) in a source
         def write_attribute(predicate, values)
           predicate = predicate.respond_to?(:uri) ? predicate.uri.to_s : predicate.to_s
           values = [ values ] unless(values.respond_to?(:each))
@@ -53,7 +57,7 @@ module TaliaCore
           end
         end
         
-        # Writes a value or object tag, depeding on the target
+        # Writes a value or object tag, depeding on the target.
         def write_target(target)
           if(target.respond_to?(:uri))
             @builder.object { @builder.text!(target.uri.to_s) }

data/lib/talia_core/active_source_parts/xml/source_reader.rb

@@ -1,21 +1,36 @@
+require 'guid'
 module TaliaCore
   module ActiveSourceParts
     module Xml
 
-      # Helper class to read an attribute hash from a Source XML
+      # A Reader for the "TaliaInternal" XML format. Check the code of this
+      # class as a simple example of how an import reader works.
+      #
+      # An example of the import format can be found in the SourceBuilder 
+      # documentation.
       class SourceReader < GenericReader
 
+        # Match the XML tags called "source", creating a new source for
+        # each of them
         element :source do
+          # Match each "attribute" tag
           nested :attribute do
+            # Read the predicate name(s) from "predicate" tag(s)
             predicate = from_element(:predicate)
             # We need to treat each value separately, as the can have 'xml:lang'
-            # attributes
+            # attributes, so we match each of the "value tags"
             nested :value do
+              # Add the internationalized value from the current element, using
+              # the "xml:lang" attribute for the language
               add_i18n predicate, from_element(:self), from_attribute('xml:lang')
             end
+            # Match all the "object" tag and add their contents as relations
             add_rel predicate, all_elements(:object)
           end
+          # Use the content of the "file" tag as a URI/filename for loading a data
+          # file
           add_file all_elements(:file)
+          @current.attributes["uri"] ||= Guid.new
         end
 
       end

data/lib/talia_core/collection.rb

@@ -1,4 +1,195 @@
 module TaliaCore
+
+  # Represents a collection of sources. In addition to being a container for 
+  # sources, the Collection class will also provide an ordering of the contained
+  # sources. 
+  #
+  # In a nutshell, this behaves like an array of sources that preserves
+  # the order when saved.
+  # 
+  # The ordering will always assign a ''unique'' integer value to each contained
+  # source that defines its position in the order of elements. The collection will
+  # keep an internal array where each object's index maps directly to its position 
+  # in the collection; the array and ordering are saved to the data store when
+  # the collection itself is saved.
+  #
+  # The collection class is relatively lightweight and will behave mostly like
+  # the underlying array - most operations are simply passed through to the array and
+  # nothing is saved before the collection itself is saved.
+  #
+  # Operations that are passed to the underlying array are: +, <<, ==, []=, at, clear,
+  # collect, delete_at, delete, each, each_index, empty?, include?, index, join, 
+  # last, length and size.
+  #
+  # This also means that all checks on added objects will only be performed when
+  # the collection is saved, and not much checking is done when the array is
+  # modified.
+  #
+  # Important: it is required that no object in the list be present more than once.
+  #
+  # In the RDF, the collection is represented as a seqContainer, using a predicate of
+  # "http://www.w3.org/1999/02/22-rdf-syntax-ns#_[index of element x]" to connect an
+  # element x with the collection.
+  #
+  # *Note*: This class replaces the previous OrderedSource class
   class Collection < Source
+    
+    include Enumerable
+    
+    has_rdf_type N::DCNS.Collection
+    has_rdf_type N::SKOS.Collection
+    has_rdf_type N::DCMIT.Collection
+
+    before_save :rewrite_order_relations
+    after_save :force_rdf_rewrite
+
+    singular_property :title, N::DCNS.title
+
+    def after_initialize
+      @autosave_rdf = false
+    end
+
+    # Creates a new Collection. Takes the same parameters as
+    # ActiveSource.new
+    def self.new(*params)
+      collection = super(*params)
+      # collection.autosave_rdf = false # Will do this by ourselves
+      collection
+    end
+
+    # Many methods are directly forwarded to the underlying array
+    [:+, :<<, :==, :[]=, :at, :clear, :collect, :delete_at, :delete, :each, 
+    :each_index, :empty?, :include?, :index, :join, :last, :length, :size].each do |method|
+      eval <<-EOM
+        def #{method}(*args, &block)
+          ordered_objects.send(:#{method}, *args, &block)
+        end
+      EOM
+    end
+    
+    # This accessor can be used for both collection items and predicates.
+    # If a number is passed in, the object will behave like an Array and
+    # the source at the given index is returned. Otherwise the parameter
+    # is treated like a predicate and it behaves like ActiveSource#[].
+    def [](index_or_predicate)
+      if(index_or_predicate.is_a?(Fixnum))
+        ordered_objects[index_or_predicate]
+      else
+        super
+      end
+    end
+    
+    # Writer that behaves in the same way as [] 
+    def []=(index_or_predicate, value)
+      if(index_or_predicate.is_a?(Fixnum))
+        ordered_objects[index_or_predicate] = value
+      else
+        super
+      end
+    end
+    
+    # Returns all contained sources in an ordered array. 
+    #
+    # The contained sources will appear in the sequential order in which they
+    # are contained in the collection, but there is no direct relation between
+    # the index in the collection and the index returned through this method.
+    # Repeated elements in the collection will be ignored.
+    def elements
+      # execute query
+      ordered_objects.compact.uniq
+    end
+      
+    # See Collection.index_to_predicate
+    def index_to_predicate(index)
+      self.class.index_to_predicate(index)
+    end
+      
+    # See Collection.predicate_to_index
+    def predicate_to_index(predicate)
+      self.class.predicate_to_index(predicate)
+    end
+    
+    # Returns the predicate that will be used for the collection element with the
+    # given index. The result will be:
+    #   http://www.w3.org/1999/02/22-rdf-syntax-ns#_<index>
+    def self.index_to_predicate(index)
+      'http://www.w3.org/1999/02/22-rdf-syntax-ns#_' << ("%06d" % index.to_i) 
+    end
+    
+    # Takes a predicate of the form produced by index_to_predicate and returns 
+    # the numeric index of the element
+    def self.predicate_to_index(predicate)
+      predicate.sub('http://www.w3.org/1999/02/22-rdf-syntax-ns#_', '').to_i
+    end
+    
+    # Reloading from database by clearing the internal array
+    def reload # :nodoc:
+      @ordered_objects = nil
+      ordered_objects
+      super
+    end
+
+    # Returns the element next to the one passed as parameter.
+    # Returns nil if there is no next object.
+    # Requires that no object in the collection is present more than once.
+    def next(object)
+      elements[elements.index(object) + 1]
+    end
+
+    # Returns the element previous to the one passed as parameter.
+    # Returns nil if there is no previous object.
+    # Requires that no object in the collection is present more than once.
+    def prev(object)
+      return nil if elements.index(object) == 0
+      elements[elements.index(object) - 1]
+    end
+
+    # Returns all the objects that are ordered in an array where the array
+    # index equals the position of the object in the ordered set. The array
+    # is zero-based, position that don't have an object attached will be set to 
+    # nil.
+    def ordered_objects
+      return @ordered_objects if(@ordered_objects)
+      relations = query
+      # Let's assume the follwing is a sane assumption ;-)
+      # Even if a one-base collection comes in, we need to push just one element
+      @ordered_objects = Array.new(relations.size)
+      # Now add the elements so that the relation property is reflected
+      # on the position in the array
+      relations.each do |rel|
+        index = rel.rel_order
+        @ordered_objects[index] = rel.object
+      end
+
+      @ordered_objects
+    end
+
+    # This will be called before saving and will completely rewrite the relations
+    # that make up the ordered store, based on the internal array
+    def rewrite_order_relations
+      return unless(@ordered_objects) # If this is nil, the relations weren't loaded in the first place
+      objects = ordered_objects # Fetch them before deleting
+      # Now destroy the existing elements
+      SemanticRelation.destroy_all(['subject_id = ? AND rel_order IS NOT NULL', self.id])
+      SemanticRelation.destroy_all(['subject_id = ? AND predicate_uri = ?', self.id, N::DCT.hasPart.to_s])
+      # rewrite from the relations array
+      objects.each_index do |index|
+        if(obj = objects.at(index)) # Check if there's a value to handle
+          # Create a new relation with an order
+          self[index_to_predicate(index)].add_record(obj, index)
+          self[N::DCT.hasPart] << obj
+        end
+      end
+    end
+    
+    def force_rdf_rewrite
+      create_rdf(:force)
+    end
+
+    # execute query and return the result
+    def query(scope = :all)
+      # execute query
+      self.semantic_relations.find(scope, :conditions => 'rel_order IS NOT NULL', :order => :rel_order)
+    end
   end
-end
+end

data/lib/talia_core/data_types/data_loader.rb

@@ -2,29 +2,94 @@ module TaliaCore
   module DataTypes
 
     # Used for attaching data items by laoding them from files and/or URLs. This will also attempt to
-    # create the correct data type for any given file.
+    # create the correct data type for any given file. See DataLoader::ClassMethods
+    
     module DataLoader
 
+      # The create_from_url method will create a new FileRecord from a 
+      # data source (file or web URL). The exact mechanism for creating
+      # the record will depend on the MIME type of the data.
+      #
+      # =How the MIME type is determined
+      # 
+      # * If the :mime_type options is provided, the system will _always_ use 
+      #   that MIME type for the new record
+      # * If the :location option is provided, the system will _always_ attempt
+      #   to determine the MIME type from the "file extension" of the location,
+      #   unless the :mime_type option is set
+      # * If the uri is a file, the system will use the file extension to
+      #   determine the MIME type automatically
+      # * If the uri is a web URL, the system will first check if the server
+      #   provided a MIME type in the response. If not, it will use the
+      #   "file extension" of the uri to determine the MIME type as above
+      #
+      # =If the loader is a FileRecord class (no loader method)
+      #
+      # If no loader method is specified, the loader will simply create a 
+      # new FileRecord object of the type specified in the loader. It will
+      # then use create_from_file (for files) or create_from_data (for 
+      # a web uri) to load the data into the new record. 
+      #
+      # Example:
+      # 
+      #  # Set a loader for png (usually done in the initializer, 
+      #  # this one is equal to the default)
+      #  TaliaCore::DataTypes::MimeMapping.add_mapping(:png, DataTypes::ImageData)
+      #  
+      #  # Call the loader
+      #  FileRecord.create_from_url('test.png')
+      #  # This will result in the following:
+      #  # DataTypes::ImageData.new.create_from_file('test.png', 'test.png')
+      # 
+      # = If the loader is a method
+      # 
+      # In case a loader method is specified, the system will simply call that
+      # method on the _class_ provided by the loader. The loader method must
+      # take the following paramters: mime_type, location, source, is_file:
+      #
+      # * _mime_type_ is the MIME type for the object being imported
+      # * _location_ is the location string for the current record. This
+      #   is either the location passed in as an option, or the base name
+      #   of the uri
+      # * _source_ is either the io object from which to read the data,
+      #   or a file name
+      # * _is_file_ is set to true in case the _source_ is a file name
+      #
+      # Example:
+      # 
+      #  # Set the handler for tiff files, usually done in the initializer
+      #  TaliaCore::DataTypes::MimeMapping.add_mapping(:tiff, :image_data, :create_iip)
+      #  
+      #  # Call the loader
+      #  FileRecord.create_from_url('test.tiff')
+      #  # This will result in the following:
+      #  # DataTypes::ImageData.create_iip(Mime::Type.lookup(:tiff), 'test.tif', 'test.tif', true)
       module ClassMethods
 
-        # Load the data from the given URL. If the mime_type option is given, the handler will always
-        # use the parameter for the MIME type (which can be a Mime::Type object or a string like
-        # 'text/html', or a mime type symbol).
+        # Load data from the given url and create FileRecord objects,
+        # as appropriate.
         #
-        # *Attention:* This method will return an *Array* of data objects. This is for those cases,
-        # where a single data file will be processed into multiple objects (e.g. IIP data).
+        # The way the FileRecord is created is determined by the MIME type 
+        # for the data. Talia has a "loader" for each MIME type - see the 
+        # MimeMapping class to see the default loaders and to find out how to
+        # configure them.
         #
-        # If the mime type is not given, the method will attempt to automatically determine the
-        # type, using the file extension or the response code.
+        # Each "loader" contains the FileRecord class that is used for new
+        # records, and (optionally) the name of a loader method which 
+        # creates the new records. If no loader method is provided, a default
+        # mechanism is used.
         #
-        # The :http_credentials option may be used to pass login information for http like this:
-        #   http_credentials = { :http_basic_authentication => [login, password] }
-        # See the openuri documentation for more.
+        # *Options*
         #
-        # You may pass the :location parameter to identify the "location" value for the new
-        # data record. In general, this is not neccessary. If the location is given, the system
-        # will *always* attempt to determine the mime type through the location parameter, unless
-        # an explicit mime type is given.
+        # [*mime_type*] Specify the MIME type to use for the import. The parameter can either be
+        #               a MIME::TYPE object, a string like 'text/html' or a MIME type symbol like :jpeg
+        # [*http_credentials*] Credentials for http authentication, if the uri requires
+        #                      that. These are the same options that openuri accepts, so see
+        #                      the documentation for that library for more information.
+        #                      _Example_: :http_credentials => { :http_basic_authentication => [login, password] }
+        # [*location*] The location (e.g. filename) for the new FileRecord. If a location is
+        #              given, it will _always_ be used to determine the MIME type, unless a
+        #              MIME type is passed explicitly as an option
         def create_from_url(uri, options = {})
           options.to_options!
           options.assert_valid_keys(:mime_type, :location, :http_credentials)
@@ -51,6 +116,8 @@ module TaliaCore
           # File.basename would use the system file separator)
           location ||= uri.rindex('/') ? uri[(uri.rindex('/') + 1)..-1] : uri
           
+          assit(!location.blank?)
+          
           if(is_file)
             mime_type ||= mime_by_location(location)
             open_and_create(mime_type, location, uri, true)
@@ -69,7 +136,9 @@ module TaliaCore
         
         # Get the mime type from the location
         def mime_by_location(location)
-          Mime::Type.lookup_by_extension(File.extname(location)[1..-1].downcase)
+          extname = File.extname(location)[1..-1]
+          assit(!extname.blank?, 'No extname found for ' << location)
+          Mime::Type.lookup_by_extension(extname.downcase)
         end
 
         # The main loader. This will handle the lookup from the mapping and the creating of the
@@ -79,8 +148,9 @@ module TaliaCore
         def open_and_create(mime_type, location, source, is_file)
           data_type = MimeMapping.loader_type_from(mime_type)
           if(data_type.is_a?(Symbol))
-            raise(ArgumentError, "No handler found for loading: #{data_type}") unless(self.respond_to?(data_type))
-            MimeMapping.class_type_from(mime_type).send(data_type, mime_type, location, source, is_file)
+            type = MimeMapping.class_type_from(mime_type)
+            raise(ArgumentError, "No handler found for loading: #{data_type}") unless(type.respond_to?(data_type))
+            type.send(data_type, mime_type, location, source, is_file)
           else
             raise(ArgumentError, "Registered handler for loading must be a method symbol or class. (#{data_type})") unless(data_type.is_a?(Class))
             data_record = data_type.new

data/lib/talia_core/data_types/data_record.rb

@@ -1,10 +1,27 @@
 module TaliaCore
   
   # Contains all data types that are handled by the Talia system. All data elements
-  # should be subclasses of DataRecord
+  # should be subclasses of DataRecord. Records that have data files attached are 
+  # subclasses of FileRecord
   module DataTypes
    
-    # ActiveRecord interface to the data record in the database
+    # Base class for all data records in Talia. This only contains a basic interface,
+    # without much functionality. All data-related methods will return a 
+    # NotImplementedError
+    #
+    # The DataRecord provides an interface to access a generic array/buffer of bytes,
+    # with the base class not making any assumptions on how these bytes are stored.
+    #
+    # Subclasses should usually provide the inferface of this class, which is more
+    # or less like the standard file interface.
+    #
+    # Each data record has a "location" field, which is roughly equivalent to the file
+    # name, and a MIME type. The default behaviour is that, if not set manually,
+    # the MIME type is automatically set before saving. It will be determined by
+    # the "file extension" of the location field.
+    #
+    # Each data record must belong to an ActiveSource. For more information on how to 
+    # handle records with files, see the FileRecord class
     class DataRecord < ActiveRecord::Base
       # Attention: These need to come before the extends, otherwise it'll blow the
       # tests
@@ -20,6 +37,7 @@ module TaliaCore
 
       # returns all bytes in the object as an array of unsigned integers
       def all_bytes
+        raise NotImplementedError
       end
     
       # Returns all_bytes as an binary string
@@ -29,18 +47,22 @@ module TaliaCore
 
       # returns the next byte from the object, or nil at EOS  
       def get_byte(close_after_single_read=false)
+        raise NotImplementedError
       end
     
       # returns the current position of the read cursor
       def position
+        raise NotImplementedError
       end
     
       # adjust the position of the read cursor
       def seek(new_position)
+        raise NotImplementedError
       end
 
       # returns the size of the object in bytes
       def size
+        raise NotImplementedError
       end
     
       # reset the cursor to the initial state