class Ezid::Identifier
Represents an EZID identifier as a resource.
@api public
Attributes
Public Class Methods
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]
# File lib/ezid/identifier.rb, line 27 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 ? metadata.delete(:shoulder) : nil mint(shoulder, metadata) else new(id, metadata) { |i| i.save } end end
Retrieves an identifier @param id [String] the EZID identifier to find @return [Ezid::Identifier] the identifier @raise [Ezid::IdentifierNotFoundError] if the identifier does not exist in EZID
# File lib/ezid/identifier.rb, line 93 def find(id) allocate.tap do |i| i.id = id i.load_metadata end end
Loads an identifier with provided remote metadata The main purpose is to provide an API in a batch processing context to instantiate Identifiers from a BatchDownload
. @see load_metadata!
@param id [String] the EZID identifier @param metadata [String, Hash, Ezid::Metadata
] the provided metadata @return [Ezid::Identifier] the identifier
# File lib/ezid/identifier.rb, line 82 def load(id, metadata = nil) allocate.tap do |i| i.id = id i.load_metadata!(metadata) 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]
# File lib/ezid/identifier.rb, line 53 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]
# File lib/ezid/identifier.rb, line 67 def modify(id, metadata) allocate.tap do |i| i.id = id i.update_metadata(metadata) i.modify! end end
# File lib/ezid/identifier.rb, line 103 def initialize(*args) raise ArgumentError, "`new` receives 0-2 arguments." if args.size > 2 options = args.last.is_a?(Hash) ? args.pop : nil @id = args.first apply_default_metadata if options if id = options.delete(:id) warn "[DEPRECATION] The `:id` hash option is deprecated and will raise an exception in 2.0. The id should be passed as the first argument to `new` or set explicitly using the attribute writer. (called by #{caller.first})" if @id raise ArgumentError, "`id' specified in both positional argument and (deprecated) hash option." end @id = id end if shoulder = options.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 client = options.delete(:client) warn "[DEPRECATION] The `:client` hash option is deprecated and ignored. It will raise an exception in 2.0. See the README for details on configuring `Ezid::Client`." end if anvl = options.delete(:metadata) update_metadata(anvl) end update_metadata(options) end yield self if block_given? end
Public Instance Methods
# File lib/ezid/identifier.rb, line 318 def client @client ||= Client.new end
Is the identifier deletable? @return [Boolean]
# File lib/ezid/identifier.rb, line 291 def deletable? persisted? && reserved? end
Deletes the identifier from EZID @see ezid.cdlib.org/doc/apidoc.html#operation-delete-identifier @return [Ezid::Identifier] the identifier @raise [Ezid::Error]
# File lib/ezid/identifier.rb, line 262 def delete raise Error, "Only persisted, reserved identifiers may be deleted: #{inspect}." unless deletable? client.delete_identifier(id) reset_metadata self.deleted = true self.persisted = false self end
Has the identifier been deleted? @return [Boolean]
# File lib/ezid/identifier.rb, line 208 def deleted? !!deleted end
# File lib/ezid/identifier.rb, line 132 def inspect id_val = if id.nil? "NEW" elsif deleted? "#{id} [DELETED]" else id end "#<#{self.class.name} id=#{id_val}>" end
Loads the metadata from EZID and marks the identifier as persisted. @return [Ezid::Identifier] the identifier @raise [Ezid::Error] the identifier is not found or other error.
# File lib/ezid/identifier.rb, line 230 def load_metadata response = client.get_identifier_metadata(id) load_remote_metadata(response.metadata) persists! self end
Loads provided metadata and marks the identifier as persisted. The main purpose is to provide an API in a batch processing context to instantiate Identifiers from a BatchDownload
. @see Ezid::BatchEnumerator @see .load @param metadata [String, Hash, Ezid::Metadata
] the provided metadata @return [Ezid::Identifier] the identifier
# File lib/ezid/identifier.rb, line 244 def load_metadata!(metadata) load_remote_metadata(metadata) persists! self end
# File lib/ezid/identifier.rb, line 157 def local_metadata @local_metadata ||= Metadata.new end
Returns the identifier metadata @return [Ezid::Metadata] the metadata
# File lib/ezid/identifier.rb, line 149 def metadata(_=nil) if !_.nil? warn "[DEPRECATION] The parameter of `metadata` is ignored and will be removed in 2.0. " \ "(called from #{caller.first})" end remote_metadata.merge(local_metadata).freeze 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.
# File lib/ezid/identifier.rb, line 184 def modify! raise Error, "Cannot modify an identifier without and id." if id.nil? modify persists! reset_metadata self end
Is the identifier persisted? @return [Boolean]
# File lib/ezid/identifier.rb, line 202 def persisted? !!persisted end
Mark the identifier as public @return [String] the new status
# File lib/ezid/identifier.rb, line 314 def public! self.status = Status::PUBLIC end
Is the identifier public? @return [Boolean]
# File lib/ezid/identifier.rb, line 279 def public? status == Status::PUBLIC end
@deprecated Use {#load_metadata} instead.
# File lib/ezid/identifier.rb, line 222 def reload warn "[DEPRECATION] `reload` is deprecated and will be removed in version 2.0. Use `load_metadata` instead. (called from #{caller.first})" load_metadata end
# File lib/ezid/identifier.rb, line 161 def remote_metadata @remote_metadata ||= Metadata.new end
Is the identifier reserved? @return [Boolean]
# File lib/ezid/identifier.rb, line 273 def reserved? status == Status::RESERVED end
Empties the (local) metadata (changes will be lost!) @return [Ezid::Identifier] the identifier
# File lib/ezid/identifier.rb, line 252 def reset warn "[DEPRECATION] `reset` is deprecated and will be removed in 2.0. Use `reset_metadata` instead. (called from #{caller.first})" reset_metadata self end
# File lib/ezid/identifier.rb, line 322 def reset_metadata local_metadata.clear remote_metadata.clear 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.
# File lib/ezid/identifier.rb, line 172 def save raise Error, "Cannot save a deleted identifier." if deleted? persist reset_metadata self end
# File lib/ezid/identifier.rb, line 143 def to_s id end
Updates the metadata and saves the identifier @param data [Hash] a hash of metadata @return [Ezid::Identifier] the identifier @raise [Ezid::Error]
# File lib/ezid/identifier.rb, line 216 def update(data={}) update_metadata(data) save end
Updates the metadata @param attrs [Hash] the metadata @return [Ezid::Identifier] the identifier
# File lib/ezid/identifier.rb, line 195 def update_metadata(attrs={}) local_metadata.update(attrs) self end
Protected Instance Methods
# File lib/ezid/identifier.rb, line 329 def method_missing(*args) local_or_remote_metadata(*args) rescue NoMethodError super end
Private Instance Methods
# File lib/ezid/identifier.rb, line 372 def apply_default_metadata update_metadata(self.class.defaults) end
# File lib/ezid/identifier.rb, line 359 def create client.create_identifier(id, local_metadata) end
# File lib/ezid/identifier.rb, line 350 def create_or_mint id ? create : mint end
# File lib/ezid/identifier.rb, line 376 def load_remote_metadata(metadata) remote_metadata.replace(metadata) end
# File lib/ezid/identifier.rb, line 337 def local_or_remote_metadata(*args) value = local_metadata.send(*args) if value.nil? && persisted? load_metadata if remote_metadata.empty? value = remote_metadata.send(*args) end value end
# File lib/ezid/identifier.rb, line 354 def mint response = client.mint_identifier(shoulder, local_metadata) self.id = response.id end
# File lib/ezid/identifier.rb, line 346 def modify client.modify_identifier(id, local_metadata) end
# File lib/ezid/identifier.rb, line 363 def persist persisted? ? modify : create_or_mint persists! end
# File lib/ezid/identifier.rb, line 368 def persists! self.persisted = true end