class Ezid::Identifier

Represents an EZID identifier as a resource.

@api public

Attributes

defaults[RW]
deleted[RW]
id[RW]
persisted[RW]
shoulder[RW]

Public Class Methods

create(*args) click to toggle source

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
find(id) click to toggle source

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
load(id, metadata = nil) click to toggle source

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
mint(*args) click to toggle source

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
modify(id, metadata) click to toggle source

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
new(*args) { |self| ... } click to toggle source
# 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

client() click to toggle source
# File lib/ezid/identifier.rb, line 318
def client
  @client ||= Client.new
end
deletable?() click to toggle source

Is the identifier deletable? @return [Boolean]

# File lib/ezid/identifier.rb, line 291
def deletable?
  persisted? && reserved?
end
delete() click to toggle source

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
deleted?() click to toggle source

Has the identifier been deleted? @return [Boolean]

# File lib/ezid/identifier.rb, line 208
def deleted?
  !!deleted
end
inspect() click to toggle source
# 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
load_metadata() click to toggle source

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
load_metadata!(metadata) click to toggle source

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
local_metadata() click to toggle source
# File lib/ezid/identifier.rb, line 157
def local_metadata
  @local_metadata ||= Metadata.new
end
metadata(_=nil) click to toggle source

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
modify!() click to toggle source

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
persisted?() click to toggle source

Is the identifier persisted? @return [Boolean]

# File lib/ezid/identifier.rb, line 202
def persisted?
  !!persisted
end
public!() click to toggle source

Mark the identifier as public @return [String] the new status

# File lib/ezid/identifier.rb, line 314
def public!
  self.status = Status::PUBLIC
end
public?() click to toggle source

Is the identifier public? @return [Boolean]

# File lib/ezid/identifier.rb, line 279
def public?
  status == Status::PUBLIC
end
reload() click to toggle source

@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
remote_metadata() click to toggle source
# File lib/ezid/identifier.rb, line 161
def remote_metadata
  @remote_metadata ||= Metadata.new
end
reserved?() click to toggle source

Is the identifier reserved? @return [Boolean]

# File lib/ezid/identifier.rb, line 273
def reserved?
  status == Status::RESERVED
end
reset() click to toggle source

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
reset_metadata() click to toggle source
# File lib/ezid/identifier.rb, line 322
def reset_metadata
  local_metadata.clear
  remote_metadata.clear
end
save() click to toggle source

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
to_s() click to toggle source
# File lib/ezid/identifier.rb, line 143
def to_s
  id
end
unavailable!(reason = nil) click to toggle source

Mark the identifier as unavailable @param reason [String] an optional reason @return [String] the new status

# File lib/ezid/identifier.rb, line 298
def unavailable!(reason = nil)
  if persisted? && reserved?
    raise Error, "Cannot make a reserved identifier unavailable."
  end
  if unavailable? and reason.nil?
    return
  end
  value = Status::UNAVAILABLE
  if reason
    value += " | #{reason}"
  end
  self.status = value
end
unavailable?() click to toggle source

Is the identifier unavailable? @return [Boolean]

# File lib/ezid/identifier.rb, line 285
def unavailable?
  status.to_s.start_with? Status::UNAVAILABLE
end
update(data={}) click to toggle source

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
update_metadata(attrs={}) click to toggle source

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

method_missing(*args) click to toggle source
Calls superclass method
# File lib/ezid/identifier.rb, line 329
def method_missing(*args)
  local_or_remote_metadata(*args)
rescue NoMethodError
  super
end

Private Instance Methods

apply_default_metadata() click to toggle source
# File lib/ezid/identifier.rb, line 372
def apply_default_metadata
  update_metadata(self.class.defaults)
end
create() click to toggle source
# File lib/ezid/identifier.rb, line 359
def create
  client.create_identifier(id, local_metadata)
end
create_or_mint() click to toggle source
# File lib/ezid/identifier.rb, line 350
def create_or_mint
  id ? create : mint
end
load_remote_metadata(metadata) click to toggle source
# File lib/ezid/identifier.rb, line 376
def load_remote_metadata(metadata)
  remote_metadata.replace(metadata)
end
local_or_remote_metadata(*args) click to toggle source
# 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
mint() click to toggle source
# File lib/ezid/identifier.rb, line 354
def mint
  response = client.mint_identifier(shoulder, local_metadata)
  self.id = response.id
end
modify() click to toggle source
# File lib/ezid/identifier.rb, line 346
def modify
  client.modify_identifier(id, local_metadata)
end
persist() click to toggle source
# File lib/ezid/identifier.rb, line 363
def persist
  persisted? ? modify : create_or_mint
  persists!
end
persists!() click to toggle source
# File lib/ezid/identifier.rb, line 368
def persists!
  self.persisted = true
end