ezid-client 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 141f157b6169fdedba53b58d11e0b9c1b26c7662
-  data.tar.gz: ef0923245729d7f20e079f3581d7647bc7cb5581
+  metadata.gz: f2baebf2aca4cada19d44f70e2e6614ad9e206ea
+  data.tar.gz: 1cbc73e6739a91a88d2cd3a7f5698d8dab1bfa3a
 SHA512:
-  metadata.gz: 16b22cbb1ba43ab241036710cfb044f66b365dd434a783a31a1370743e063517a530df12b2f72c24c0f3575dabdb8045e49fa673fc01306621d46fe2a8a88683
-  data.tar.gz: f329532cc4d162575b0c3c14a76d8b7ca253963486686e73565ec4f31debd1c498f5804034f2713badac901b0875d7a27eba322a488bd6ef48f073b01246ce70
+  metadata.gz: 042582d5276928c9444bf60eb1d1ed851795d072145c2e33e13d8a08d25be121bb797992ed941a2e1eba5cae1a9f980d26c24196f4ffa59edbf9a3d1d5a46161
+  data.tar.gz: f6be1c6c06c59f8aec88b78664927aa0fbd8c92d090f920ad5c4c9edf99202c397f6a8444b2210da12c1f5c1ebc7240401286dc09fb447b7ef9f9ee65cccc414

data/README.md

@@ -27,17 +27,17 @@ Or install it yourself as:
 
 [Mint an identifier on a shoulder](http://ezid.cdlib.org/doc/apidoc.html#operation-mint-identifier)
 
+*Added in v1.4.0:* `Ezid::Identifier.mint` class method.
+
 ```
->> identifier = Ezid::Identifier.create(shoulder: "ark:/99999/fk4")
-I, [2014-12-04T15:06:02.428445 #86655]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk4rx9d523
-I, [2014-12-04T15:06:03.249793 #86655]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4rx9d523
-=> #<Ezid::Identifier id="ark:/99999/fk4rx9d523" status="public" target="http://ezid.cdlib.org/id/ark:/99999/fk4rx9d523" created="2014-12-04 20:06:02 UTC">
->> identifier.id
-=> "ark:/99999/fk4rx9d523"
+>> identifier = Ezid::Identifier.mint("ark:/99999/fk4")
+I, [2016-03-01T22:20:08.505323 #35148]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk4tq65d6k
+=> #<Ezid::Identifier id=ark:/99999/fk4tq65d6k>
 >> identifier.status
+I, [2016-03-01T22:20:22.323650 #35148]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4tq65d6k
 => "public"
 >> identifier.target
-=> "http://ezid.cdlib.org/id/ark:/99999/fk4rx9d523"
+=> "http://ezid.cdlib.org/id/ark:/99999/fk4tq65d6k"
 ```
 
 A default shoulder can be configured:
@@ -59,19 +59,19 @@ end
 New identifiers will then be minted on the default shoulder when a shoulder is not specified:
 
 ```
->> identifier = Ezid::Identifier.create
+>> identifier = Ezid::Identifier.mint
 I, [2014-12-09T11:22:34.499860 #32279]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk43f4wd4v
-I, [2014-12-09T11:22:35.317181 #32279]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk43f4wd4v
-=> #<Ezid::Identifier id="ark:/99999/fk43f4wd4v" status="public" target="http://ezid.cdlib.org/id/ark:/99999/fk43f4wd4v" created="2014-12-09 16:22:35 UTC">
+=> #<Ezid::Identifier id="ark:/99999/fk43f4wd4v">
 ```
 
 [Create a specific identifier](http://ezid.cdlib.org/doc/apidoc.html#operation-create-identifier)
 
+*Changed in v1.4.0:* `Ezid::Identifier.create` now expects the first argument to be the identifier (String) to create; the second optional argument is a hash of metadata elements. Passing the identifier in an `:id` hash option is deprecated and will be removed in v2.0. The `:shoulder` hash option is likewise deprecated; use `Ezid::Identifier.mint(shoulder, metadata)` instead.
+
 ```
->> identifier = Ezid::Identifier.create(id: "ark:/99999/fk4rx9d523/12345")
+>> identifier = Ezid::Identifier.create("ark:/99999/fk4rx9d523/12345")
 I, [2014-12-09T11:21:42.077297 #32279]  INFO -- : EZID CreateIdentifier -- success: ark:/99999/fk4rx9d523/12345
-I, [2014-12-09T11:21:42.808534 #32279]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4rx9d523/12345
-=> #<Ezid::Identifier id="ark:/99999/fk4rx9d523/12345" status="public" target="http://ezid.cdlib.org/id/ark:/99999/fk4rx9d523/12345" created="2014-12-09 16:21:42 UTC">
+=> #<Ezid::Identifier id="ark:/99999/fk4rx9d523/12345">
 ```
 
 **Retrieve** (Get Metadata)
@@ -91,30 +91,34 @@ I, [2014-12-04T15:07:00.648676 #86655]  INFO -- : EZID GetIdentifierMetadata --
 => "http://example.com"
 >> identifier.save
 I, [2014-12-09T11:24:26.321801 #32279]  INFO -- : EZID ModifyIdentifier -- success: ark:/99999/fk43f4wd4v
-I, [2014-12-09T11:24:27.039288 #32279]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk43f4wd4v
-=> #<Ezid::Identifier id="ark:/99999/fk43f4wd4v" status="public" target="http://example.com" created="2014-12-09 16:22:35 UTC">
+=> #<Ezid::Identifier id="ark:/99999/fk43f4wd4v">
 >> identifier.target
+I, [2014-12-09T11:24:27.039288 #32279]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk43f4wd4v
 => "http://example.com"
 ```
 
+*Added in v1.4.0:* `Ezid::Identifier.modify(id, metadata)` class method. In support of more efficient updating of known identifiers, this method skips the GetIdentifierMetadata request used by `.find`. The operation will raise the `Ezid::IdentifierNotFoundError` if the EZID identifier does not exist.
+
 **Delete**
 
 *Identifier status must be "reserved" to delete.* http://ezid.cdlib.org/doc/apidoc.html#operation-delete-identifier
 
 ```
->> identifier = Ezid::Identifier.create(shoulder: "ark:/99999/fk4", status: "reserved")
-I, [2014-12-04T15:12:39.976930 #86734]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk4n58pc0r
-I, [2014-12-04T15:12:40.693256 #86734]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4n58pc0r
-=> #<Ezid::Identifier id="ark:/99999/fk4n58pc0r" status="reserved" target="http://ezid.cdlib.org/id/ark:/99999/fk4n58pc0r" created="2014-12-04 20:12:39 UTC">
+>> identifier = Ezid::Identifier.mint("ark:/99999/fk4", status: "reserved")
+I, [2016-03-01T22:26:08.645858 #36701]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk4pz5fm1b
+=> #<Ezid::Identifier id=ark:/99999/fk4pz5fm1b>
 >> identifier.delete
-I, [2014-12-04T15:12:48.853964 #86734]  INFO -- : EZID DeleteIdentifier -- success: ark:/99999/fk4n58pc0r
-=> #<Ezid::Identifier id="ark:/99999/fk4n58pc0r" DELETED>
+I, [2016-03-01T22:26:14.829731 #36701]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4pz5fm1b
+I, [2016-03-01T22:26:15.711390 #36701]  INFO -- : EZID DeleteIdentifier -- success: ark:/99999/fk4pz5fm1b
+=> #<Ezid::Identifier id=ark:/99999/fk4pz5fm1b [DELETED]>
 ```
 
 ## Batch Download
 
 See http://ezid.cdlib.org/doc/apidoc.html#parameters. Repeated values should be given as an array value for the parameter key.
 
+*Added in v1.3.0:* `Ezid::BatchDownload` class.
+
 ```
 >> batch = Ezid::BatchDownload.new(:csv)
  => #<Ezid::BatchDownload format=:csv>
@@ -161,33 +165,6 @@ Notes:
 
 Accessors are also implemented for the `crossref`, `datacite`, and `erc` elements as described in the EZID API documentation.
 
-**Setting default metadata values**
-
-Default metadata values can be set:
-
-```ruby
-Ezid::Client.configure do |config|
-  # set multiple defaults with a hash
-  config.identifier.defaults = {status: "reserved", profile: "dc"}
-  # or set individual elements
-  config.identifier.defaults[:status] = "reserved"
-  config.identifier.defaults[:profile] = "dc"
-end
-```
-
-Then new identifiers will receive the defaults:
-
-```
->> identifier = Ezid::Identifier.create(shoulder: "ark:/99999/fk4")
-I, [2014-12-09T11:38:37.335136 #32279]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk4zs2w500
-I, [2014-12-09T11:38:38.153546 #32279]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4zs2w500
-=> #<Ezid::Identifier id="ark:/99999/fk4zs2w500" status="reserved" target="http://ezid.cdlib.org/id/ark:/99999/fk4zs2w500" created="2014-12-09 16:38:38 UTC">
->> identifier.profile
-=> "dc"
->> identifier.status
-=> "reserved"
-```
-
 ## Authentication
 
 Credentials can be provided in any -- or a combination -- of these ways:

data/VERSION

@@ -1 +1 @@
-1.3.0
+1.4.0

data/ezid-client.gemspec

@@ -24,4 +24,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 3.1"
+  spec.add_development_dependency "rspec-its"
 end

data/lib/ezid/batch_download.rb

@@ -1,7 +1,6 @@
 require "hashie"
 require "net/http"
 require "uri"
-require_relative "reserved_metadata"
 
 module Ezid
   class BatchDownloadError < Error; end

data/lib/ezid/client.rb

@@ -6,7 +6,6 @@ require_relative "configuration"
 require_relative "session"
 require_relative "metadata"
 require_relative "identifier"
-require_relative "proxy_identifier"
 require_relative "batch_download"
 
 Dir[File.expand_path("../responses/*.rb", __FILE__)].each { |m| require m }

data/lib/ezid/error.rb

@@ -1,3 +1,11 @@
 module Ezid
   class Error < ::RuntimeError; end
+
+  # The requested identifier was not found
+  class IdentifierNotFoundError < Error; end
+
+  # The requested action is not allowed
+  class NotAllowedError < Error; end
+
+  class DeletionError < Error; end
 end

data/lib/ezid/identifier.rb

@@ -6,53 +6,111 @@ module Ezid
   #
   class Identifier
 
-    attr_reader :client
-    attr_accessor :id, :shoulder, :metadata, :state
-
-    private :state, :state=, :id=
-
-    # Attributes to display on inspect
-    INSPECT_ATTRS = %w( id status target created ).freeze
+    attr_accessor :id, :shoulder, :persisted, :deleted
+    private :persisted=, :persisted, :deleted=, :deleted
 
     class << self
       attr_accessor :defaults
 
       # Creates or mints an identifier (depending on arguments)
       # @see #save
+      # @overload create(id, metadata=nil)
+      #   Creates an identifier
+      #   @param id [String] the identifier to create
+      #   @param metadata [Hash] the metadata to set on the identifier
+      # @overload create(metadata=nil)
+      #   Mints an identifier
+      #   @deprecated Use {.mint} instead
+      #   @param metadata [Hash] the metadata to set on the identifier
+      # @return [Ezid::Identifier] the new identifier
+      # @raise [Ezid::Error]
+      def create(*args)
+        raise ArgumentError, "`mint` receives 0-2 arguments." if args.size > 2
+        if args.first.is_a?(Hash)
+          warn "[DEPRECATION] Sending a hash as the first argument to `create` is deprecated and will raise an exception in 2.0. Use `create(id, metadata)` or `mint(metadata)` instead. (called from #{caller.first})"
+          metadata = args.first
+          id = metadata.delete(:id)
+        else
+          id, metadata = args
+        end
+        if id.nil?
+          warn "[DEPRECATION] Calling `create` without an id will raise an exception in 2.0. Use `mint` instead. (called from #{caller.first})"
+          shoulder = metadata.delete(:shoulder)
+          mint(shoulder, metadata)
+        else
+          new(id, metadata) { |i| i.save }
+        end
+      end
+
+      # Mints a new identifier
+      # @overload mint(shoulder, metadata=nil)
+      #   @param shoulder [String] the EZID shoulder on which to mint
+      #   @param metadata [Hash] the metadata to set on the identifier
+      # @overload mint(metadata=nil)
+      #   @param metadata [Hash] the metadata to set on the identifier
       # @return [Ezid::Identifier] the new identifier
       # @raise [Ezid::Error]
-      def create(attrs = {})
-        identifier = new(attrs)
-        identifier.save
+      def mint(*args)
+        raise ArgumentError, "`mint` receives 0-2 arguments." if args.size > 2
+        metadata = args.last.is_a?(Hash) ? args.pop : nil
+        new(metadata) do |i|
+          i.shoulder = args.first
+          i.save
+        end
+      end
+
+      # Modifies the metadata of an existing identifier.
+      # @param id [String] the EZID identifier
+      # @param metadata [Hash] the metadata to update on the identifier
+      # @return [Ezid::Identifier] the identifier
+      # @raise [Ezid::IdentifierNotFoundError]
+      def modify(id, metadata)
+        i = allocate
+        i.id = id
+        i.update_metadata(metadata)
+        i.modify!
       end
 
       # Retrieves an identifier
+      # @param id [String] the EZID identifier to find
       # @return [Ezid::Identifier] the identifier
-      # @raise [Ezid::Error] if the identifier does not exist in EZID
+      # @raise [Ezid::IdentifierNotFoundError] if the identifier does not exist in EZID
       def find(id)
-        identifier = new(id: id)
-        identifier.load_metadata
+        i = allocate
+        i.id = id
+        i.load_metadata
       end
     end
 
     self.defaults = {}
 
-    def initialize(args={})
-      @client = args.delete(:client) || Client.new
-      @id = args.delete(:id)
-      @shoulder = args.delete(:shoulder)
-      @state = :new
-      self.metadata = Metadata.new args.delete(:metadata)
-      update_metadata self.class.defaults.merge(args) # deprecate?
+    def initialize(*args)
+      raise ArgumentError, "`new` receives 0-2 arguments." if args.size > 2
+      data = args.last.is_a?(Hash) ? args.pop : nil
+      @id = args.first
+      apply_default_metadata
+      if data
+        if shoulder = data.delete(:shoulder)
+          warn "[DEPRECATION] The `:shoulder` hash option is deprecated and will raise an exception in 2.0. Use `Ezid::Identifier.mint(shoulder, metadata)` to mint an identifier. (called by #{caller.first})"
+          @shoulder = shoulder
+        end
+        if anvl = data.delete(:metadata)
+          update_metadata(anvl)
+        end
+        update_metadata(data)
+      end
+      yield self if block_given?
     end
 
     def inspect
-      attrs = if deleted?
-                "id=\"#{id}\" DELETED"
-              else
-                INSPECT_ATTRS.map { |attr| "#{attr}=#{send(attr).inspect}" }.join(", ")
-              end
-      "#<#{self.class.name} #{attrs}>"
+      id_val = if id.nil?
+                 "NEW"
+               elsif deleted?
+                 "#{id} [DELETED]"
+               else
+                 id
+               end
+      "#<#{self.class.name} id=#{id_val}>"
     end
 
     def to_s
@@ -60,11 +118,16 @@ module Ezid
     end
 
     # Returns the identifier metadata
-    # @param load [Boolean] - flag to load the metadata from EZID if stale (default: `true`)
     # @return [Ezid::Metadata] the metadata
-    def metadata(load = true)
-      load_metadata if load && stale?
-      @metadata
+    def metadata(_=nil)
+      if !_.nil?
+        warn "[DEPRECATION] The parameter of `metadata` is deprecated and will be removed in 2.0. (called from #{caller.first})"
+      end
+      @metadata ||= Metadata.new
+    end
+
+    def remote_metadata
+      @remote_metadata ||= Metadata.new
     end
 
     # Persist the identifer and/or metadata to EZID.
@@ -77,27 +140,41 @@ module Ezid
     def save
       raise Error, "Cannot save a deleted identifier." if deleted?
       persist
-      reset
+      reset_metadata
+      self
+    end
+
+    # Force a modification of the EZID identifier -- i.e.,
+    #   assumes previously persisted without confirmation.
+    # @return [Ezid::Identifier] the identifier
+    # @raise [Ezid::Error] if `id` is nil
+    # @raise [Ezid::IdentifierNotFoundError] if EZID identifier does not exist.
+    def modify!
+      raise Error, "Cannot modify an identifier without and id." if id.nil?
+      modify
+      persists!
+      reset_metadata
+      self
     end
 
     # Updates the metadata
     # @param attrs [Hash] the metadata
     # @return [Ezid::Identifier] the identifier
     def update_metadata(attrs={})
-      attrs.each { |k, v| send("#{k}=", v) }
+      metadata.update(attrs)
       self
     end
 
     # Is the identifier persisted?
     # @return [Boolean]
     def persisted?
-      state == :persisted
+      !!persisted
     end
 
     # Has the identifier been deleted?
     # @return [Boolean]
     def deleted?
-      state == :deleted
+      !!deleted
     end
 
     # Updates the metadata and saves the identifier
@@ -111,24 +188,26 @@ module Ezid
 
     # @deprecated Use {#load_metadata} instead.
     def reload
-      warn "[DEPRECATION] `reload` is deprecated and will be removed in version 2.0. Use `load_metadata` instead."
+      warn "[DEPRECATION] `reload` is deprecated and will be removed in version 2.0. Use `load_metadata` instead. (called from #{caller.first})"
       load_metadata
     end
 
-    # Loads the metadata from EZID (local changes will be lost!)
+    # Loads the metadata from EZID
     # @return [Ezid::Identifier] the identifier
     # @raise [Ezid::Error]
     def load_metadata
       response = client.get_identifier_metadata(id)
-      self.metadata = Metadata.new(response.metadata)
-      self.state = :persisted
+      # self.remote_metadata = Metadata.new(response.metadata)
+      remote_metadata.replace(response.metadata)
+      persists!
       self
     end
 
     # Empties the (local) metadata (changes will be lost!)
     # @return [Ezid::Identifier] the identifier
     def reset
-      clear_metadata
+      warn "[DEPRECATION] `reset` is deprecated and will be removed in 2.0. Use `reset_metadata` instead. (called from #{caller.first})"
+      reset_metadata
       self
     end
 
@@ -139,8 +218,10 @@ module Ezid
     def delete
       raise Error, "Only persisted, reserved identifiers may be deleted: #{inspect}." unless deletable?
       client.delete_identifier(id)
-      self.state = :deleted
-      reset
+      reset_metadata
+      self.deleted = true
+      self.persisted = false
+      self
     end
 
     # Is the identifier reserved?
@@ -190,22 +271,32 @@ module Ezid
       self.status = Status::PUBLIC
     end
 
+    def client
+      @client ||= Client.new
+    end
+
+    def reset_metadata
+      metadata.clear unless metadata.empty?
+      remote_metadata.clear unless remote_metadata.empty?
+    end
+
     protected
 
-    def method_missing(method, *args)
-      metadata.send(method, *args)
+    def method_missing(*args)
+      local_or_remote_metadata(*args)
     rescue NoMethodError
       super
     end
 
     private
 
-    def stale?
-      persisted? && metadata(false).empty?
-    end
-
-    def clear_metadata
-      metadata(false).clear
+    def local_or_remote_metadata(*args)
+      value = metadata.send(*args)
+      if value.nil? && persisted?
+        load_metadata if remote_metadata.empty?
+        value = remote_metadata.send(*args)
+      end
+      value
     end
 
     def modify
@@ -227,7 +318,15 @@ module Ezid
 
     def persist
       persisted? ? modify : create_or_mint
-      self.state = :persisted
+      persists!
+    end
+
+    def persists!
+      self.persisted = true
+    end
+
+    def apply_default_metadata
+      update_metadata(self.class.defaults)
     end
 
   end