talia_core 0.5.4 → 0.7.0

data/lib/talia_core/data_types/iip_loader.rb

@@ -3,14 +3,47 @@ require 'tmpdir'
 module TaliaCore
   module DataTypes
 
-    # Special module that contains the DataLoader methods to create IIP image data
+    # Loader module for IipData records. IIP records should always be created
+    # by using the #create_iip method in this module as a loader. Check the
+    # DataLoader documentation to find out how to configure loaders for 
+    # different MIME types.
+    #
+    # = How does this work?
+    #
+    # The loader will take the original image, and create two new DataRecords
+    # which contain three different versions of the image:
+    #
+    # * An ImageData record will contain the original version of the image.
+    #   This will contain the original file if the original is a jpeg or png 
+    #   image. Otherwise it will be converted to png.
+    # * An IipData record which contains a thumbnail of the original image and
+    #   create the pyramidal version of it in the IIP server's directory. The
+    #   location of the IipData will contain the path to the pyramidal image
+    #   on the server
+    #
+    # = Using existing images
+    #
+    # Creating the pyramid images can be a time-consuming process and it may
+    # be useful to separate this from the actual import process (if, for example
+    # you want to re-import the same data set several times). The Talia
+    # distribution contains a <tt>prepare_images</tt> script that will take the
+    # original files from a given directory and create the converted files in
+    # another location, using the subdirectories <tt>thumbs</tt>, <tt>pyramids</tt>
+    # and <tt>originals</tt> respectively.
+    #
+    # If a directory with "prepared files" exists, the <tt>prepared_images</tt>
+    # option in the _environment_ to the path to the directory. When the loader
+    # see that environment variable, it will automatically load the prepared
+    # images from that directory.
     module IipLoader
 
 
       # Loads an image for the given file. This is a tad more complex than loading
       # the data into a data record: It will create both an IIP data object and
-      # an Image data object. 
+      # an Image data object. If the original is an IO stream, a temp file will
+      # be created for the conversions. See above for more.
       def create_iip(mime_type, location, source, is_file)
+        # Create the new records
         iip_record = TaliaCore::DataTypes::IipData.new
         image_record = TaliaCore::DataTypes::ImageData.new
         records = [iip_record, image_record]
@@ -35,32 +68,40 @@ module TaliaCore
         records
       end
 
-      # Rewrite the file location for original image files (to .png)
+      # Rewrite the <tt>location</tt> field (filename) for "original image" data
+      # record, changing the extension to .png
       def orig_location(location)
         File.basename(location, File.extname(location)) + '.png'
       end
 
-      # Indicates if the given mime type requires a conversion for the
-      # original image
+      # Indicates if an original image with the given mime type
+      # should be converted to png for the "original image" record
       def convert_original?(mime_type)
         !([:jpeg, :png].include?(mime_type.to_sym))
       end
 
-      # Create the elements from a file
+      # Pass in the empty data records (for original and iip), and
+      # fill each one by calling #create_from_file with the 
+      # given file
       def create_from_files(location, file, records)
         records.each { |rec| rec.create_from_file(location, file) }
       end
 
-      # Create the elements from a stream
+      # Pass in the empty data records (for original and iip), and
+      # fill them by reading the data from the io stream and
+      # calling  #create_from_data on each record
       def create_from_stream(location, io, records)
         data = io.read
         records.each { |rec| rec.create_from_data(location, data)}
       end
 
-      # Attempts to create an IipData object with pre-prepared images if possible
+      # Attempts to create the records from pre-prepared images, if possible.
       # Returns true if (and only if) the object has been created with existing
-      # data. Always fals if the data_record is not an IipData object or the
-      # :prepared_images option is not set.
+      # data. Always false if the data_record is not an IipData object or the
+      # <tt>prepared_images</tt> option is not set.
+      # 
+      # If this method returns true, the images have been successfully prepared
+      # from pre-prepared images.
       def prepare_image_from_existing!(iip_record, image_record, url, location)
         return false unless(iip_record.is_a?(TaliaCore::DataTypes::IipData) && image_record.is_a?(TaliaCore::DataTypes::ImageData))
         return false unless((prep = ENV['prepared_images']) && prep.to_s.downcase != 'no' && prep.to_s.downcase != 'false')
@@ -68,62 +109,67 @@ module TaliaCore
         file_ext = File.extname(url)
         file_base = File.basename(url, file_ext)
 
+        # Get the file paths for each prepared image: thumb, pyramid and original
         thumb_file = File.join( ENV['prepared_images'], 'thumbs', "#{file_base}.gif")
         pyramid_file = File.join( ENV['prepared_images'], 'pyramids', "#{file_base}.tif")
+        # Use a pattern for the original file, since we don't know the extensions
         orig_file_pattern = File.join(ENV['prepared_images'], 'originals', "#{file_base}.*")
-        # We need to fix the pattern, also the Dir[] doesn't like unescaped brackets
-        orig_file_pattern.gsub!(/\[/, '\\[')
-          orig_file_pattern.gsub!(/\]/, '\\]')
-          orig_file_l = Dir[orig_file_pattern]
-          raise(ArgumentError, 'Original find not found for ' + url) unless(orig_file_l.size > 0)
-          orig_file = orig_file_l.first
-          assit_block { %w(.jpg .jpeg .png).include?(File.extname(orig_file).downcase) }
-
-          iip_record.create_from_existing(thumb_file, pyramid_file)
-          image_record.create_from_file(location, orig_file)
-
-          true
-        end
+        # We need to fix the pattern
+        orig_file_pattern.gsub!(/\[/, '\\[') # Escape brackets, Dir[] doesn't like them
+        orig_file_pattern.gsub!(/\]/, '\\]')
+        orig_file_l = Dir[orig_file_pattern]
+        raise(ArgumentError, 'Original find not found for ' + url) unless(orig_file_l.size > 0)
+        orig_file = orig_file_l.first # Original is the first file matching the pattern
+        assit_block { %w(.jpg .jpeg .png).include?(File.extname(orig_file).downcase) }
+
+        # Now create the existing records from the files
+        iip_record.create_from_existing(thumb_file, pyramid_file)
+        image_record.create_from_file(location, orig_file)
+
+        true
+      end
 
-        # Little helper to decide how to open the original image
-        def open_original_image(thing, is_file, current_type, &block)
-          if(is_file)
-            open_original_image_file(thing, &block) 
-          else
-            open_original_image_stream(thing, current_type, &block)
-          end
+      # Little helper to decide how to open the original image
+      def open_original_image(thing, is_file, current_type, &block)
+        if(is_file)
+          open_original_image_file(thing, &block) 
+        else
+          open_original_image_stream(thing, current_type, &block)
         end
+      end
 
-        # Same as open_original_image_file, but getting the data from a stream.
-        def open_original_image_stream(io, type, &block)
-          # First load this from the web to a temp file
-          tempfile = File.join(Dir.tmpdir, "talia_down_#{rand 10E16}.#{type.to_sym}")
-          begin
-            File.open(tempfile, 'w') do |fio|
-              fio << io.read # Download the file
-            end
-            assit(File.exist?(tempfile))
-            open_original_image_file(tempfile, &block)
-          ensure
-            FileUtils.rm(tempfile) if(File.exist?(tempfile))
+      # Same as open_original_image_file, but getting the data from a stream.
+      # This writes the data to a temp file and calls open_original_file on it
+      # The temporary file is deleted after the operation
+      def open_original_image_stream(io, type, &block)
+        # First load this from the web to a temp file
+        tempfile = File.join(Dir.tmpdir, "talia_down_#{rand 10E16}.#{type.to_sym}")
+        begin
+          File.open(tempfile, 'w') do |fio|
+            fio << io.read # Download the file
           end
+          assit(File.exist?(tempfile))
+          open_original_image_file(tempfile, &block)
+        ensure
+          FileUtils.rm(tempfile) if(File.exist?(tempfile))
         end
+      end
 
-        # Opens the "original" image for the given file. This will convert the
-        # image to PNG image and the yield the io object for the PNG.
-        def open_original_image_file(filename)
-          converted_file = File.join(Dir.tmpdir, "talia_convert_#{rand 10E16}.png")
-          begin
-            TaliaUtil::ImageConversions.to_png(filename, converted_file)
-            File.open(converted_file) do |io|
-              yield(io)
-            end
-          ensure
-            FileUtils.rm(converted_file) if(File.exist?(converted_file))
+      # Opens the "original" image for the given file. This will convert the
+      # image to PNG image and the yield the io object for the PNG.
+      def open_original_image_file(filename)
+        converted_file = File.join(Dir.tmpdir, "talia_convert_#{rand 10E16}.png")
+        begin
+          TaliaUtil::ImageConversions.to_png(filename, converted_file)
+          File.open(converted_file) do |io|
+            yield(io)
           end
+        ensure
+          FileUtils.rm(converted_file) if(File.exist?(converted_file))
         end
+      end
 
 
-      end # Ending modules and such
-    end
-  end
+    end # Ending modules and such
+  end
+end

data/lib/talia_core/data_types/image_data.rb

@@ -1,11 +1,13 @@
 module TaliaCore
   module DataTypes
     
-    # Class to manage image data type
+    # A FileRecord that contains an image.
     class ImageData < FileRecord
       
       # return the mime_type for a file
       def extract_mime_type(location)
+        # TODO: This may work automatically if all the MIME types
+        # are configured correctly (?)
         case File.extname(location).downcase
         when '.bmp'
           'image/bmp'

data/lib/talia_core/data_types/media_link.rb

@@ -3,7 +3,10 @@ module TaliaCore
     
     # Data class that contains just a link to a remote data element (and no
     # locally stored data at all). The uri for the link is stored in the location
-    # field
+    # field.
+    #
+    # *Note*: It is not possible to store data in media links, so all data-related
+    # methods will raise an exception
     class MediaLink < DataRecord
       
       def all_bytes

data/lib/talia_core/data_types/mime_mapping.rb

@@ -1,21 +1,48 @@
 module TaliaCore
   module DataTypes
 
-    # Mapping from Mime types to data classes and importing methods. Currently uses a fixed 
-    # default mapping. If the mime type is not known, it will use a fallback default handler.
+    # Mapping from Mime types to data classes and importing methods for DataRecord.
     #
-    # The mapping can be configured in Rails' initializer files. Example:
+    # See the DataTypes::DataLoader module to see how the import works. In a nutshell,
+    # each MIME type can be connected either to a DataTypes::FileRecord type that will
+    # be used for new data records, or the MIME type can be connected to a handler 
+    # method that will do the creation.
     #
-    #   TaliaCore::DataTypes::MimeMapping(:tiff, :image_data, :create_iip)
+    # = Default Mappings
+    #
+    # See the source code of the mapping_hash method for the detailed default mapping.
+    # It goes something like this: 
+    #
+    # * All image types (:jpeg, :tiff, :png, :gif, ...) use DataTypes::ImageData
+    # * HTML, XML and all "transcription" types (:html, :xml, :tei, ...) use DataTypes::XmlData
+    # * :text uses DataTypes::SimpleText
+    # * :pdf uses DataTypes::PdfData
+    # * The default (for unknow types) is to use DataTypes::FileRecord
+    #
+    # = Configure the MIME mappings for Talia
+    # 
+    # The mapping can be configured in Rails' initializer files (e.g. 
+    # config/initializers/talia.rb):
+    #
+    #   TaliaCore::DataTypes::MimeMapping.add_mapping(:tiff, :image_data, :create_iip)
+    #
+    # Add a mapping for each MIME type that you need, or where you want to change
+    # the default mapping
     class MimeMapping
 
       class << self
 
-        # Gets the data class for the given mime type
+        # Gets the data class for the given mime type. For loaders configured
+        # through add_mapping, this will always return the class corresponding
+        # to data_class. (Otherwise it will return the data_class configured 
+        # in the default mapping)
         def class_type_from(mime_type)
           mapping_for(mime_type)[:type]
         end
 
+        # Return the "loader type" for the given MIME type. This will return the 
+        # handler (as a symbol, see add_mapping) if set.
+        # If no handler is set, it will return the data_class (as class_type_from). 
         def loader_type_from(mime_type)
           map = mapping_for(mime_type)
           map[:loader] || map[:type]
@@ -23,23 +50,17 @@ module TaliaCore
         
         # Set a new mapping for the given MIME type. If only a class is given, this
         # will use the class to create new data records from. If a symbol is given
-        # for the class name, this will take the corresponding class from
+        # for data_class, this will take the corresponding class from
         # TaliaCore::DataTypes.
         #
-        # The loader method can be a symbol, if given it must correspond to a *class* 
-        # method that can be called on type_class and which accepts exactly 4 parameters,
-        # which will be passed in during record creation
-        # 
-        # * Mime type of the record 
-        # * 'location' field of the record
-        # * The record source - this is a descriptive string with either the url
-        #   or the file name from which the data should be fetched
-        # * The is_file flag. This will be true if the source is the name of a
-        #   regular file. Otherwise, the source field should be interpreted as
-        #   a URL.
-        # == Example handler method
-        #
-        #   def data_loader(mime_type, location, source, is_file)
+        # = Examples
+        #  
+        #  # Uses DataTypes::ImageData#create_iip to create new records
+        #  TaliaCore::DataTypes::MimeMapping.add_mapping(:tiff, :image_data, :create_iip)
+        #  
+        #  # Use the DataTypes::ImageData class for new data records, and create records
+        #  # in the default way (using create_with_file or similar)
+        #  TaliaCore::DataTypes::MimeMapping.add_mapping(:png, DataTypes::ImageData)
         def add_mapping(mime_type, data_class, handler = nil)
           mapping = {}
           if(!data_class.is_a?(Class))
@@ -54,23 +75,8 @@ module TaliaCore
           true
         end
         
-        private
-
-        def symbol_for(mime_type)
-          mime_type = Mime::Type.lookup(mime_type) unless(mime_type.is_a?(Mime::Type))
-          mime_type.to_sym
-        end
-
-        def mapping_for(mime_type)
-          mapping = mapping_hash[symbol_for(mime_type)]
-          TaliaCore.logger.warn { "No data class registered for mime type #{mime_type.inspect}, trying default handler." } unless(mapping)
-          mapping ||= mapping_hash[:default]
-
-          raise(ArgumentError, "No data class registered for type #{mime_type.inspect}") unless(mapping)
-          mapping
-        end
-
-        # Currently there is only the default mapping
+        # Returns the current mapping. This will be automatically initialized with
+        # the default mappings.
         def mapping_hash
           @mapping ||= {
             :xml => { :type => DataTypes::XmlData },
@@ -92,10 +98,31 @@ module TaliaCore
             :default => { :type => FileRecord }
           }
         end
+        
+        private
+        
+        # Returns the symbol that corresponds to a given MIME type. The MIME type
+        # can be a Mime::Type object, a MIME string like 'text/html' or a MIME
+        # symbol like :jpeg
+        def symbol_for(mime_type)
+          mime_type = Mime::Type.lookup(mime_type) unless(mime_type.is_a?(Mime::Type))
+          mime_type.to_sym
+        end
+
+        # Return the mapping for the given MIME type. If no mapping is defined for the
+        # MIME type, it will log a warning and use the "default" mapping.
+        def mapping_for(mime_type)
+          mapping = mapping_hash[symbol_for(mime_type)]
+          TaliaCore.logger.warn { "No data class registered for mime type #{mime_type.inspect}, trying default handler." } unless(mapping)
+          mapping ||= mapping_hash[:default]
+
+          raise(ArgumentError, "No data class registered for type #{mime_type.inspect}") unless(mapping)
+          mapping
+        end
 
       end
 
     end
 
   end
-end
+end

data/lib/talia_core/data_types/path_helpers.rb

@@ -5,6 +5,7 @@ module TaliaCore
     module PathHelpers
       
       module ClassMethods
+        
         # Path used to store temporary files.
         def tempfile_path
           @@tempfile_path ||= File.join(TALIA_ROOT, 'tmp', 'data_records')
@@ -15,22 +16,26 @@ module TaliaCore
           @@data_path ||= File.join(TALIA_ROOT, 'data')
         end
         
-      
-            
-        # Extract the filename.
-        def extract_filename(file_data)
-          file_data.original_filename if file_data.respond_to?(:original_filename)
-        end
-      
       end      
       
-      # Return the full file path related to the data directory
+      # Return the full file path for this record. If the relative
+      # flag is set, this will only return the relative path inside
+      # the data directory
       def file_path(relative = false)
         File.join(data_directory(relative), self.id.to_s)
       end
       
       # Gets the path that will be used for serving the image as a static
-      # resource. Nil if the prefix isn't set
+      # resource.
+      #
+      # This will return nil unless the <tt>static_data_prefix</tt> option
+      # is set in the configuration. This option defines a URL prefix for
+      # static files. 
+      #
+      # If the prefix is set, this method will return a URL that can be used
+      # access the current file as a static asset. To use this, the data
+      # directory has to be available on a web server at the 
+      # <tt>static_data_prefix</tt>
       def static_path
         prefix = TaliaCore::CONFIG['static_data_prefix']
         return unless(prefix)
@@ -38,13 +43,16 @@ module TaliaCore
         "#{prefix}/#{class_name}/#{("00" + self.id.to_s)[-3..-1]}/#{self.id}"
       end
       
-      # Path used to store temporary files.
-      # This is a wrapper for the tempfile_path class method.
+      # See ClassMethods.tempfile_path
       def tempfile_path
         self.class.tempfile_path
       end
     
-      # Return the data directory for a specific data file
+      # Return the _directory_ in which the file for the current record is stored.
+      # If the relative flag is set, it will only return the relative path
+      # inside the main data directory.
+      #
+      # The paths will look something like: <tt>.../XmlData/031/</tt>
       def data_directory(relative = false)
         class_name = self.class.name.gsub(/(.*::)/, '')
         if relative == false
@@ -54,19 +62,17 @@ module TaliaCore
         end
       end
     
-      # Path used to store data files.
-      # This is a wrapper for the data_path class method.
+      # See ClassMethods.data_path
       def data_path
         self.class.data_path
       end
       
-      # Return the full path of the current attachment.
+      # Cached version of #file_path
       def full_filename
         @full_filename ||= self.file_path #File.join(data_path, class_name, location)
       end
       
-      # Extract the filename.
-      # This is a wrapper for the extract_filename class method.
+      # See ClassMethods.extract_filename
       def extract_filename(file_data)
         self.class.extract_filename(file_data)
       end