ezid-client 0.3.0 → 0.4.0

data/lib/ezid/identifier.rb

@@ -0,0 +1,170 @@
+module Ezid
+  class Identifier
+
+    attr_reader :id, :client
+    attr_accessor :shoulder, :metadata
+
+    INSPECT_ATTRS = %w( id status target created )
+
+    PUBLIC = "public"
+    RESERVED = "reserved"
+    UNAVAILABLE = "unavailable"
+
+    class << self
+      # @return [Ezid::Identifier] the new identifier
+      # @raise [Ezid::Error]
+      def create(attrs = {})
+        identifier = new(attrs)
+        identifier.save
+      end
+
+      # @return [Ezid::Identifier] the identifier
+      # @raise [Ezid::Error] if the identifier does not exist in EZID
+      def find(id)
+        identifier = new(id: id)
+        identifier.reload
+      end
+    end
+
+    def initialize(args={})
+      @client = args.delete(:client) || Client.new
+      @id = args.delete(:id)
+      @shoulder = args.delete(:shoulder)
+      @metadata = Metadata.new(args.delete(:metadata))
+      update_attributes(args)
+      @deleted = false
+    end
+
+    def inspect
+      attrs = if deleted?
+                "id=\"#{id}\" DELETED"
+              else
+                INSPECT_ATTRS.map { |attr| "#{attr}=\"#{send(attr)}\"" }.join(" ")
+              end
+      "#<#{self.class.name} #{attrs}>"
+    end
+
+    def to_s
+      id
+    end
+
+    # Persist the identifer and/or metadata to EZID.
+    #   If the identifier is already persisted, this is an update operation;
+    #   Otherwise, create (if it has an id) or mint (if it has a shoulder)
+    #   the identifier.
+    # @return [Ezid::Identifier] the identifier
+    # @raise [Ezid::Error] if the identifier is deleted, or the host responds
+    #   with an error status.
+    def save
+      raise Error, "Cannot save a deleted identifier." if deleted?
+      if persisted?
+        modify
+      else
+        create_or_mint
+      end
+      reload
+    end
+
+    def update_attributes(attrs={})
+      attrs.each { |k, v| send("#{k}=", v) }
+    end
+
+    # Is the identifier persisted?
+    # @return [Boolean]
+    def persisted?
+      return false if deleted?
+      !!(id && created)
+    end
+
+    # Has the identifier been deleted?
+    # @return [Boolean]
+    def deleted?
+      @deleted
+    end
+
+    # @return [Ezid::Identifier] the identifier
+    # @raise [Ezid::Error]
+    def update(data)
+      metadata.update(data)
+      save
+    end
+
+    # @return [Ezid::Identifier] the identifier
+    # @raise [Ezid::Error]
+    def reload
+      refresh_metadata
+      self
+    end
+
+    # Empties the (local) metadata
+    # @return [Ezid::Identifier] the identifier
+    def reset
+      clear_metadata
+      self
+    end
+
+    # @return [Ezid::Identifier] the identifier
+    # @raise [Ezid::Error]
+    def delete
+      raise Error, "Status must be \"reserved\" to delete (status: \"#{status}\")." unless reserved?
+      client.delete_identifier(id)
+      @deleted = true
+      reset
+    end
+
+    def method_missing(name, *args)
+      return metadata.send(name, *args) if metadata.respond_to?(name)
+      super
+    end
+
+    def reserved?
+      status == RESERVED
+    end
+
+    def public?
+      status == PUBLIC
+    end
+
+    def unavailable?
+      status == UNAVAILABLE
+    end
+
+    private
+
+    def refresh_metadata
+      response = client.get_identifier_metadata(id)
+      @metadata.replace(response.metadata)
+    end
+
+    def clear_metadata
+      @metadata.clear
+    end
+
+    def modify
+      client.modify_identifier(id, metadata)
+    end
+
+    def create_or_mint
+      if id
+        create
+      elsif shoulder
+        mint
+      else
+        raise Error, "Unable to create or mint identifier when neither `id' nor `shoulder' present."
+      end
+    end
+
+    def mint
+      response = client.mint_identifier(shoulder, metadata)
+      @id = response.id
+    end
+
+    def create
+      client.create_identifier(id, metadata)
+    end
+
+    def init_metadata(args={})
+    end
+
+  end
+end

data/lib/ezid/metadata.rb

@@ -1,52 +1,31 @@
-require "forwardable"
+require "delegate"
+require_relative "metadata_elements"
 
 module Ezid
   #
   # EZID metadata collection for an identifier
   #
   # @api public
-  class Metadata
-    extend Forwardable
-    include Enumerable
-
-    # The metadata elements hash
-    attr_reader :elements
-
-    def_delegators :elements, :each, :keys, :values, :empty?, :[], :[]=
-
-    # EZID metadata profiles
-    PROFILES = %w( erc dc datacite crossref )
-
-    # Public status
-    PUBLIC = "public"
-
-    # Reserved status
-    RESERVED = "reserved"
-
-    # Unavailable status
-    UNAVAILABLE = "unavailable"
-    
-    # EZID identifier status values
-    STATUS_VALUES = [PUBLIC, RESERVED, UNAVAILABLE].freeze
-
-    # EZID internal read-only metadata elements
-    INTERNAL_READONLY_ELEMENTS = %w( _owner _ownergroup _created _updated _shadows _shadowedby _datacenter ).freeze
+  #
+  class Metadata < SimpleDelegator
 
-    # EZID internal writable metadata elements
-    INTERNAL_READWRITE_ELEMENTS = %w( _coowners _target _profile _status _export _crossref ).freeze        
+    include MetadataElements
 
-    # EZID internal metadata elements
-    INTERNAL_ELEMENTS = (INTERNAL_READONLY_ELEMENTS + INTERNAL_READWRITE_ELEMENTS).freeze
-    
     # EZID metadata field/value separator
     ANVL_SEPARATOR = ": "
 
+    ELEMENT_VALUE_SEPARATOR = " | "
+
     # Characters to escape in element values on output to EZID
+    # @see http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
     ESCAPE_VALUES_RE = /[%\r\n]/
 
-    ESCAPE_KEYS_RE = /[%:\r\n]/
+    # Characters to escape in element names on output to EZID
+    # @see http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
+    ESCAPE_NAMES_RE = /[%:\r\n]/
 
     # Character sequence to unescape from EZID
+    # http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
     UNESCAPE_RE = /%\h\h/
 
     # A comment line
@@ -57,16 +36,18 @@ module Ezid
 
     # A line ending
     LINE_ENDING_RE = /\r?\n/
-
+    
     def initialize(data={})
-      @elements = coerce(data)
+      super(coerce(data))
     end
 
     # Output metadata in EZID ANVL format
     # @see http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
     # @return [String] the ANVL output
-    def to_anvl
-      escape_keys.zip(escape_values).map { |e| e.join(ANVL_SEPARATOR) }.join("\n")
+    def to_anvl(include_readonly = true)
+      elements = __getobj__.dup # copy, don't modify!
+      elements.reject! { |k, v| RESERVED_READONLY_ELEMENTS.include?(k) } unless include_readonly
+      escape_elements(elements).map { |e| e.join(ANVL_SEPARATOR) }.join("\n")
     end
 
     def to_s
@@ -77,55 +58,20 @@ module Ezid
     # @param data [String, Hash, Ezid::Metadata] the data to add
     # @return [Ezid::Metadata] the updated metadata
     def update(data)
-      elements.update(coerce(data))
+      __getobj__.update(coerce(data))
       self
     end
 
-    # Identifier status
-    # @return [String] the status
-    def status
-      reader("_status")
-    end
-
-    # The time the identifier was created
-    # @return [Time] the time
-    def created
-      value = reader("_created")
-      return Time.at(value.to_i) if value
-      value
-    end
-
-    # The time the identifier was last updated
-    # @return [Time] the time
-    def updated
-      value = reader("_updated")
-      return Time.at(value.to_i) if value
-      value
-    end
-
-    # The identifier's preferred metadata profile
-    # @see http://ezid.cdlib.org/doc/apidoc.html#metadata-profiles
-    # @return [String] the profile
-    def profile
-      reader("_profile")
-    end
-
-    # The identifier's target URL
-    # @return [String] the URL
-    def target
-      reader("_target")
+    # Replaces the collection with new metadata
+    # @param data [String, Hash, Ezid::Metadata] the metadata replacing the current metadata
+    # @return [Ezid::Metadata] the replaced metadata
+    def replace(data)
+      __getobj__.replace(coerce(data))
+      self
     end
 
     private
 
-    def reader(element)
-      self[element]
-    end
-
-    def writer(element, value)
-      self[element] = value
-    end
-
     # Coerce data into a Hash of elements
     def coerce(data)
       begin
@@ -135,25 +81,35 @@ module Ezid
       end
     end
 
+    # Coerce hash keys to strings
     def stringify_keys(hsh)
-      hsh.keys.map(&:to_s).zip(hsh.values).to_h
+      hsh.each_with_object({}) { |(k, v), memo| memo[k.to_s] = v }
     end
 
-    def escape_keys
-      keys.map { |k| escape(ESCAPE_KEYS_RE, k) }
+    # Escape elements hash keys and values
+    def escape_elements(hsh)
+      hsh.each_with_object({}) do |(n, v), memo|
+        memo[escape_name(n)] = escape_value(v)
+      end
+    end
+
+    # Escape an element name
+    def escape_name(n)
+      escape(ESCAPE_NAMES_RE, n)
     end
 
-    def escape_values
-      values.map { |v| escape(ESCAPE_VALUES_RE, v) }
+    # Escape an element value
+    def escape_value(v)
+      escape(ESCAPE_VALUES_RE, v)
     end
 
-    # Escape value for sending to EZID host
+    # Escape string for sending to EZID host
     # @see http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
     # @param re [Regexp] the regular expression to match for escaping
-    # @param value [String] the value to escape
-    # @return [String] the escaped value
-    def escape(re, value)
-      value.gsub(re) { |m| URI.encode_www_form_component(m, Encoding::UTF_8) }
+    # @param s [String] the string to escape
+    # @return [String] the escaped string
+    def escape(re, s)
+      s.gsub(re) { |m| URI.encode_www_form_component(m.force_encoding(Encoding::UTF_8)) }
     end
 
     # Unescape value from EZID host (or other source)
@@ -165,14 +121,16 @@ module Ezid
     end
     
     # Coerce a string of metadata (e.g., from EZID host) into a Hash
+    # @note EZID host does not send comments or line continuations.
     # @param data [String] the string to coerce
     # @return [Hash] the hash of coerced data
     def coerce_string(data)
-      data.gsub(COMMENT_RE, "")
-        .gsub(LINE_CONTINUATION_RE, " ")
-        .split(LINE_ENDING_RE)
-        .map { |line| line.split(ANVL_SEPARATOR, 2).map { |v| unescape(v).strip } }
-        .to_h
+      data.gsub!(COMMENT_RE, "")
+      data.gsub!(LINE_CONTINUATION_RE, " ")
+      data.split(LINE_ENDING_RE).each_with_object({}) do |line, memo|
+        element, value = line.split(ANVL_SEPARATOR, 2)
+        memo[unescape(element.strip)] = unescape(value.strip)
+      end
     end
 
   end

data/lib/ezid/metadata_elements.rb

@@ -0,0 +1,89 @@
+require "active_support"
+
+module Ezid
+  module MetadataElements
+    extend ActiveSupport::Concern
+    
+    DC_ELEMENTS = %w( creator title publisher date type )
+    DATACITE_ELEMENTS = %w( creator title publisher publicationyear resourcetype )
+    ERC_ELEMENTS = %w( who what when )
+
+    RESERVED_TIME_ELEMENTS = %w( _created _updated )
+    RESERVED_READONLY_ELEMENTS = %w( _owner _ownergroup _shadows _shadowedby _datacenter _created _updated )
+    RESERVED_READWRITE_ELEMENTS = %w( _coowners _target _profile _status _export _crossref )
+    RESERVED_ELEMENTS = RESERVED_READONLY_ELEMENTS + RESERVED_READWRITE_ELEMENTS + RESERVED_TIME_ELEMENTS
+
+    included do
+      reserved_accessor *(RESERVED_READWRITE_ELEMENTS - ["_crossref"])
+      reserved_reader *(RESERVED_READONLY_ELEMENTS - RESERVED_TIME_ELEMENTS)
+      reserved_time_reader *RESERVED_TIME_ELEMENTS
+
+      profile_accessor :dc, *DC_ELEMENTS
+      profile_accessor :datacite, *DATACITE_ELEMENTS
+      profile_accessor :erc, *ERC_ELEMENTS
+      
+      element_accessor "datacite", "crossref", "_crossref"
+    end
+
+    module ClassMethods
+      def reserved_accessor(*elements)
+        reserved_reader(*elements)
+        reserved_writer(*elements)
+      end
+
+      def reserved_reader(*elements)
+        elements.each do |element|
+          define_method(element.sub("_", "")) { reader(element) }
+        end
+      end
+
+      def reserved_time_reader(*elements)
+        elements.each do |element|
+          define_method(element.sub("_", "")) do
+            time = reader(element).to_i
+            return nil if time == 0 # value is nil or empty string                                                    
+            Time.at(time).utc
+          end
+        end
+      end
+
+      def reserved_writer(*elements)
+        elements.each do |element|
+          define_method("#{element.sub('_', '')}=") do |value| 
+            writer(element, value)
+          end
+        end
+      end
+
+      def profile_accessor(profile, *elements)
+        elements.each do |element|
+          define_method("#{profile}_#{element}") do
+            reader("#{profile}.#{element}")
+          end
+        
+          define_method("#{profile}_#{element}=") do |value|
+            writer("#{profile}.#{element}", value)
+          end     
+        end
+      end
+
+      def element_accessor(*elements)
+        elements.each do |element|
+          define_method(element) { reader(element) }
+          define_method("#{element}=") { |value| writer(element, value) }
+        end
+      end
+    end
+
+    private
+
+    def reader(element)
+      self[element]
+    end
+
+    def writer(element, value)
+      self[element] = value
+    end
+
+  end
+end