ezid-client 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 034acbeee70fe9fe84f4e8b26c90e30cb158501c
-  data.tar.gz: 57a075ccf73a3c29e2fe2945acb4a9675a8c3224
+  metadata.gz: 1a8c3c449a9447e7176421f705a537c9919442a9
+  data.tar.gz: 9d16f67d27605bc7066f6dd3df2e9a9be5dc4e26
 SHA512:
-  metadata.gz: 11a3a93987cccc2c665abf3a0cd1f822980186ce0547aae500f5cd509ccdf5868b9fc41bcef16215a6fac4c0ef1f09e0eddd32f8baf11a5d347fc66154df3d09
-  data.tar.gz: b5193f91303db313b4a385d2c557d19b2ee97290acfa08ec912c4201d8164504a62d9f962a4a6d67d194ebfbadd81b27a04659dbae139c8327b4271f7be1e99a
+  metadata.gz: 94f6cf47f52bb030e0f7cf4442ef5aedbcb31f9348ebb1e528a11e9727b2a3e94260002ff43dd2fb1240fdeadbc3b2adde341fa83e5ad6b28f44e9e0f982eedd
+  data.tar.gz: 4a70172958a729e05c2b5ba2d5a51081e5a4865135c9107111045a9993f9e5881f10d3ca50d0b180d2f1b73cc383913955111beeac1660da9f6635f17754ef01

data/README.md

@@ -113,7 +113,43 @@ I, [2014-12-04T15:12:48.853964 #86734]  INFO -- : EZID DELETE ark:/99999/fk4n58p
 
 ## Metadata handling
 
-Although "EZID imposes no requirements on the presence or form of citation metadata"[*](http://ezid.cdlib.org/doc/apidoc.html#metadata-requirements-mapping), `ezid-client` is intended to support the EZID [reserved metadata elements](http://ezid.cdlib.org/doc/apidoc.html#internal-metadata) and [metadata profiles](http://ezid.cdlib.org/doc/apidoc.html#metadata-profiles). While it is possible to use the client to send and receive any metadata, the object methods are geared towards the defined elements.  Therefore it was seen fit, for example, to map the method `Ezid::Identifier#status` to the `_status` element.  Likewise, all the reserved elements, except for `_crossref`, have readers and -- for user-writable elements -- writers without the leading underscores.  Since there are both `_crossref` and `crossref` elements, their accessors match the elements names.  Similarly, accessors for metadata profile elements use underscores in place of dots -- for example, `Ezid::Identifer#dc_title` and `#dc_title=` for the `dc.title` element.
+In order to ease metadata management access to EZID [reserved metadata elements](http://ezid.cdlib.org/doc/apidoc.html#internal-metadata) and [metadata profiles](http://ezid.cdlib.org/doc/apidoc.html#metadata-profiles) is provided through `#method_missing` according to these heuristics:
+
+**Reserved elements** can be read and written using the name of the element without the leading underscore:
+
+```ruby
+>> identifier.status                 # reads "_status" element
+=> "public"
+>> identifier.status = "unavailable" # writes "_status" element
+=> "unavailable"
+```
+
+Notes:
+- `_crossref` is an exception because `crossref` is also the name of a metadata profile and a special element.  Use `identifier._crossref` to read and `identifier._crossref = value` to write.
+- Reserved elements which are not user-writeable do not implement writers.
+- Special readers are implemented for reserved elements having date/time values -- `_created` and `_updated` -- which convert the string time values of EZID to Ruby `Time` instances.
+
+**Metadata profile elements** can be read and written using the name of the element, replacing the dot (".") with an underscore:
+
+```ruby
+>> identifier.dc_type           # reads "dc.type" element
+=> "Collection"
+>> identifier.dc_type = "Image" # writes "dc.type" element
+=> "Image"
+```
+
+**Registering custom metadata elements**
+
+Custom metadata element accessors can be created by a registration process:
+
+```ruby
+Ezid::Client.configure do |config|
+  # register the element "custom"
+  config.metadata.register_element :custom
+  # register the element "dc.identifier" under the accessor :dc_identifier
+  config.metadata.register_element :dc_identifier, name: "dc.identifier"
+end
+```
 
 **Setting default metadata values**
 

data/VERSION

@@ -1 +1 @@
-0.9.1
+0.10.0

data/lib/ezid/configuration.rb

@@ -54,5 +54,9 @@ module Ezid
       Identifier
     end
 
+    def metadata
+      Metadata
+    end
+
   end
 end

data/lib/ezid/identifier.rb

@@ -1,20 +1,16 @@
-require "forwardable"
-
 module Ezid
   #
   # Represents an EZID identifier as a resource.
   #
+  # Ezid::Identifier delegates access to registered metadata elements through #method_missing.
+  #
   # @api public
   #
   class Identifier
-    extend Forwardable
 
     attr_reader :id, :client
     attr_accessor :shoulder, :metadata
 
-    def_delegators :metadata, *(Metadata.elements.readers)
-    def_delegators :metadata, *(Metadata.elements.writers)
-
     # Attributes to display on inspect
     INSPECT_ATTRS = %w( id status target created )
 
@@ -126,10 +122,11 @@ module Ezid
     end
 
     # Deletes the identifier from EZID
+    # @see http://ezid.cdlib.org/doc/apidoc.html#operation-delete-identifier
     # @return [Ezid::Identifier] the identifier
     # @raise [Ezid::Error]
     def delete
-      raise Error, "Status must be \"reserved\" to delete (status: \"#{status}\")." unless reserved?
+      raise Error, "Only persisted, reserved identifiers may be deleted: #{inspect}." unless deletable?
       client.delete_identifier(id)
       @deleted = true
       reset
@@ -150,40 +147,71 @@ module Ezid
     # Is the identifier unavailable?
     # @return [Boolean]
     def unavailable?
-      status == UNAVAILABLE
+      status =~ /^#{UNAVAILABLE}/
     end
 
-    private
-
-    def refresh_metadata
-      response = client.get_identifier_metadata(id)
-      @metadata = Metadata.new(response.metadata)
+    # Is the identifier deletable?
+    # @return [Boolean]
+    def deletable?
+      persisted? && reserved?
     end
 
-    def clear_metadata
-      @metadata.clear
+    # Mark the identifier as unavailable
+    # @param reason [String] an optional reason 
+    # @return [String] the new status
+    def unavailable!(reason = nil)
+      raise Error, "Cannot make a reserved identifier unavailable." if persisted? && reserved?
+      value = UNAVAILABLE
+      value << " | #{reason}" if reason
+      self.status = value
     end
 
-    def modify
-      client.modify_identifier(id, metadata)
+    # Mark the identifier as public
+    # @return [String] the new status
+    def public!
+      self.status = PUBLIC
     end
 
-    def create_or_mint
-      id ? create : mint
-    end
+    protected
 
-    def mint
-      response = client.mint_identifier(shoulder, metadata)
-      @id = response.id
-    end
+      def method_missing(method, *args)
+        metadata.send(method, *args)
+      rescue NoMethodError
+        super
+      end
 
-    def create
-      client.create_identifier(id, metadata)
-    end
+    private
+
+      def refresh_metadata
+        response = client.get_identifier_metadata(id)
+        @metadata = Metadata.new(response.metadata)
+      end
+
+      def clear_metadata
+        @metadata.clear
+      end
+
+      def modify
+        client.modify_identifier(id, metadata)
+      end
+
+      def create_or_mint
+        id ? create : mint
+      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)
+        @metadata = Metadata.new(args.delete(:metadata))
+        update_metadata(self.class.defaults.merge(args))
+      end
 
-    def init_metadata(args)
-      @metadata = Metadata.new(args.delete(:metadata))
-      update_metadata(self.class.defaults.merge(args))
-    end
   end
 end

data/lib/ezid/metadata.rb

@@ -1,9 +1,8 @@
 require "delegate"
-require "singleton"
 
 module Ezid
   #
-  # EZID metadata collection for an identifier
+  # EZID metadata collection for an identifier.
   #
   # @note Although this API is not private, its direct use is discouraged.
   #   Instead use the metadata element accessors through Ezid::Identifier.
@@ -64,71 +63,53 @@ module Ezid
     # @see http://ezid.cdlib.org/doc/apidoc.html#internal-metadata
     RESERVED_ELEMENTS = RESERVED_READONLY_ELEMENTS + RESERVED_READWRITE_ELEMENTS
 
-    # Metadata element registry
-    class ElementRegistry < SimpleDelegator
-      include Singleton
-
-      def initialize
-        super(Hash.new)
-      end
-
-      def readers
-        keys
-      end
-
-      def writers
-        keys.select { |k| self[k].writer }.map(&:to_s).map { |k| k.concat("=") }.map(&:to_sym)
-      end
-    end
-
     def self.initialize!
       register_elements
-      define_element_accessors
     end
 
-    def self.elements
-      ElementRegistry.instance
+    def self.registered_elements
+      @@registered_elements ||= {}
     end
 
     def self.register_elements
       register_profile_elements
       register_reserved_elements
-      elements.freeze
     end
 
-    def self.define_element_accessors
-      elements.each do |accessor, element|
-        define_method(accessor) { reader(element.name) }
-
-        if element.writer
-          define_method("#{accessor}=") { |value| writer(element.name, value) }
-        end
+    def self.register_element(accessor, opts={})
+      if element = registered_elements[accessor.to_sym]
+        raise Error, "Element \"#{element.name}\" already registered under key :#{accessor}"
       end
+      writer = opts.fetch(:writer, true)
+      name = opts.fetch(:name, accessor.to_s)
+      registered_elements[accessor.to_sym] = Element.new(name, writer).freeze
     end
 
-    def self.register_element(accessor, element, opts={})
-      writer = opts.fetch(:writer, true)
-      elements[accessor] = Element.new(element, writer).freeze
+    def self.register_profile_element(profile, element)
+      register_element("#{profile}_#{element}", name: "#{profile}.#{element}")
     end
 
-    def self.register_profile_elements
-      PROFILES.each do |profile, profile_elements|
-        profile_elements.each do |element|
-          register_element("#{profile}_#{element}".to_sym, "#{profile}.#{element}")
+    def self.register_profile_elements(profile = nil)
+      if profile
+        PROFILES[profile].each { |element| register_profile_element(profile, element) }
+      else
+        PROFILES.keys.each do |profile|
+          register_profile_elements(profile)
+          register_element(profile) unless profile == "dc"
         end
-        register_element(profile.to_sym, profile) unless profile == "dc"
       end
     end
 
     def self.register_reserved_elements
       RESERVED_ELEMENTS.each do |element|
-        accessor = ((element == "_crossref") ? element : element.sub("_", "")).to_sym
-        register_element(accessor, element, writer: RESERVED_READWRITE_ELEMENTS.include?(element))
+        accessor = (element == "_crossref") ? element : element.sub("_", "")
+        register_element(accessor, name: element, writer: RESERVED_READWRITE_ELEMENTS.include?(element))
       end
     end
 
-    private_class_method :register_element, :register_elements, :register_reserved_elements,
-                         :register_profile_elements, :define_element_accessors
+    private_class_method :register_elements,
+                         :register_reserved_elements,
+                         :register_profile_elements
 
     def initialize(data={})
       super(coerce(data))
@@ -147,8 +128,28 @@ module Ezid
       to_anvl
     end
 
+    def registered_elements
+      self.class.registered_elements
+    end
+
+    protected
+
+      def method_missing(method, *args)
+        return registered_reader(method) if registered_reader?(method, *args)
+        return registered_writer(method, *args) if registered_writer?(method, *args)
+        super
+      end
+
     private
 
+      def registered_reader?(accessor, *args)
+        args.empty? && registered_elements.include?(accessor)
+      end
+
+      def registered_reader(accessor)
+        reader registered_elements[accessor].name
+      end
+
       def reader(element)
         value = self[element]
         if RESERVED_TIME_ELEMENTS.include?(element)
@@ -158,6 +159,17 @@ module Ezid
         value
       end
 
+      def registered_writer?(method, *args)
+        return false unless method.to_s.end_with?("=") && args.size == 1
+        accessor = method.to_s.sub("=", "").to_sym
+        registered_elements.include?(accessor) && registered_elements[accessor].writer
+      end
+
+      def registered_writer(method, *args)
+        accessor = method.to_s.sub("=", "").to_sym
+        writer(registered_elements[accessor].name, *args)
+      end
+
       def writer(element, value)
         self[element] = value
       end

data/spec/unit/identifier_spec.rb

@@ -108,7 +108,7 @@ module Ezid
       context "when id and `created' are present" do
         before do
           allow(subject).to receive(:id) { "ark:/99999/fk4fn19h88" }
-          allow(subject.metadata).to receive(:created) { Time.at(1416507086) }
+          subject.metadata["_created"] = "1416507086"
         end
         it "should be true" do
           expect(subject).to be_persisted
@@ -117,11 +117,28 @@ module Ezid
     end
 
     describe "#delete" do
-      subject { described_class.new(id: "id", status: "reserved") }
-      it "should delete the identifier" do
-        expect(subject.client).to receive(:delete_identifier).with("id") { double(id: "id") }
-        subject.delete
-        expect(subject).to be_deleted
+      context "when the identifier is reserved" do
+        subject { described_class.new(id: "id", status: Identifier::RESERVED) }
+        context "and is persisted" do
+          before { allow(subject).to receive(:persisted?) { true } }
+          it "should delete the identifier" do
+            expect(subject.client).to receive(:delete_identifier).with("id") { double(id: "id") }
+            subject.delete
+            expect(subject).to be_deleted
+          end          
+        end
+        context "and is not persisted" do
+          before { allow(subject).to receive(:persisted?) { false } }
+          it "should raise an exception" do
+            expect { subject.delete }.to raise_error
+          end
+        end
+      end
+      context "when identifier is not reserved" do
+        subject { described_class.new(id: "id", status: Identifier::PUBLIC) }
+        it "should raise an exception" do
+          expect { subject.delete }.to raise_error
+        end
       end
     end
 
@@ -167,23 +184,70 @@ module Ezid
     end
 
     describe "boolean status methods" do
-      context "when the status is 'public'" do
-        before { allow(subject.metadata).to receive(:status) { Identifier::PUBLIC } }
+      context "when the identifier is public" do
+        before { subject.public! }
         it { is_expected.to be_public }
         it { is_expected.not_to be_reserved }
         it { is_expected.not_to be_unavailable }
       end
-      context "when the status is 'reserved'" do
-        before { allow(subject.metadata).to receive(:status) { Identifier::RESERVED } }
+      context "when the identifier is reserved" do
+        before { subject.status = Identifier::RESERVED }
         it { is_expected.not_to be_public }
         it { is_expected.to be_reserved }
         it { is_expected.not_to be_unavailable }
       end
-      context "when the status is 'unavailable'" do
-        before { allow(subject.metadata).to receive(:status) { Identifier::UNAVAILABLE } }
-        it { is_expected.not_to be_public }
-        it { is_expected.not_to be_reserved }
-        it { is_expected.to be_unavailable }
+      context "when the identifier is unavailable" do
+        context "and it has no reason" do
+          before { subject.unavailable! }
+          it { is_expected.not_to be_public }
+          it { is_expected.not_to be_reserved }
+          it { is_expected.to be_unavailable }
+        end
+        context "and it has a reason" do
+          before { subject.unavailable!("withdrawn") }
+          it { is_expected.not_to be_public }
+          it { is_expected.not_to be_reserved }
+          it { is_expected.to be_unavailable }
+        end
+      end
+    end
+
+    describe "status-changing methods" do
+      describe "#unavailable!" do
+        context "when the identifier is reserved" do
+          subject { described_class.new(id: "id", status: Identifier::RESERVED) }
+          context "and persisted" do
+            before { allow(subject).to receive(:persisted?) { true } }
+            it "should raise an exception" do
+              expect { subject.unavailable! }.to raise_error
+            end
+          end
+          context "and not persisted" do
+            before { allow(subject).to receive(:persisted?) { false } }
+            it "should changed the status" do
+              expect { subject.unavailable! }.to change(subject, :status).from(Identifier::RESERVED).to(Identifier::UNAVAILABLE)
+            end
+          end
+        end
+        context "when the identifier is public" do
+          subject { described_class.new(id: "id", status: Identifier::PUBLIC) }
+          context "and no reason is given" do
+            it "should change the status" do
+              expect { subject.unavailable! }.to change(subject, :status).from(Identifier::PUBLIC).to(Identifier::UNAVAILABLE)
+            end
+          end
+          context "and a reason is given" do
+            it "should change the status and append the reason" do
+              expect { subject.unavailable!("withdrawn") }.to change(subject, :status).from(Identifier::PUBLIC).to("#{Identifier::UNAVAILABLE} | withdrawn")
+            end
+          end
+        end
+      end
+      describe "#public!" do
+        subject { described_class.new(id: "id", status: Identifier::UNAVAILABLE) }
+        it "should change the status" do
+          expect { subject.public! }.to change(subject, :status).from(Identifier::UNAVAILABLE).to(Identifier::PUBLIC)
+        end
       end
     end
 

data/spec/unit/metadata_spec.rb

@@ -33,6 +33,7 @@ module Ezid
         end
       end
     end
+
     describe "metadata profiles" do
       Metadata::PROFILES.each do |profile, elements|
         describe "the '#{profile}' metadata profile" do
@@ -65,6 +66,22 @@ module Ezid
       end
     end
 
+    describe "custom element" do
+      let(:element) { Metadata::Element.new("custom", true) }
+      before do
+        allow(subject.registered_elements).to receive(:include?).with(:custom) { true } 
+        allow(subject.registered_elements).to receive(:[]).with(:custom) { element } 
+      end
+      it "should have a reader" do
+        expect(subject).to receive(:reader).with("custom")
+        subject.custom
+      end
+      it "should have a writer" do
+        expect(subject).to receive(:writer).with("custom", "value")
+        subject.custom = "value"
+      end
+    end
+
     describe "ANVL output" do
       let(:elements) do
         { "_target" => "http://example.com/path%20with%20spaces",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ezid-client
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - David Chandek-Stark
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-18 00:00:00.000000000 Z
+date: 2014-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler