Class: Ezid::Identifier

Inherits:
Object
  • Object
show all
Defined in:
lib/ezid/identifier.rb

Overview

Represents an EZID identifier as a resource.

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) {|_self| ... } ⇒ Identifier

Returns a new instance of Identifier.

Yields:

  • (_self)

Yield Parameters:

Raises:

  • (ArgumentError) 


103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# 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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(*args) ⇒ Object (protected) 



329
330
331
332
333
 
# File 'lib/ezid/identifier.rb', line 329

def method_missing(*args)
  local_or_remote_metadata(*args)
rescue NoMethodError
  super
end

Class Attribute Details

.defaults ⇒ Object 



13
14
15
 
# File 'lib/ezid/identifier.rb', line 13

def defaults
  @defaults
end

Instance Attribute Details

#id ⇒ Object 



9
10
11
 
# File 'lib/ezid/identifier.rb', line 9

def id
  @id
end

#shoulder ⇒ Object 



9
10
11
 
# File 'lib/ezid/identifier.rb', line 9

def shoulder
  @shoulder
end

Class Method Details

.create(id, metadata = nil) ⇒ Ezid::Identifier .create(metadata = nil) ⇒ Ezid::Identifier

Creates or mints an identifier (depending on arguments)

Overloads:

  • .create(id, metadata = nil) ⇒ Ezid::Identifier

    Creates an identifier

    Parameters:

    • id (String) —

      the identifier to create

    • metadata (Hash) (defaults to: nil) —

      the metadata to set on the identifier

  • .create(metadata = nil) ⇒ Ezid::Identifier
    Deprecated.

    Use mint instead

    Mints an identifier

    Parameters:

    • metadata (Hash) (defaults to: nil) —

      the metadata to set on the identifier

Returns:

Raises:

See Also:



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# 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) ⇒ Ezid::Identifier

Retrieves an identifier

Parameters:

  • id (String) —

    the EZID identifier to find

Returns:

Raises:



93
94
95
96
97
98
 
# 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) ⇒ Ezid::Identifier

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.

Parameters:

  • id (String) —

    the EZID identifier

  • metadata (String, Hash, Ezid::Metadata) (defaults to: nil) —

    the provided metadata

Returns:

See Also:



82
83
84
85
86
87
 
# 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(shoulder, metadata = nil) ⇒ Ezid::Identifier .mint(metadata = nil) ⇒ Ezid::Identifier

Mints a new identifier

Overloads:

  • .mint(shoulder, metadata = nil) ⇒ Ezid::Identifier

    Parameters:

    • shoulder (String) —

      the EZID shoulder on which to mint

    • metadata (Hash) (defaults to: nil) —

      the metadata to set on the identifier

  • .mint(metadata = nil) ⇒ Ezid::Identifier

    Parameters:

    • metadata (Hash) (defaults to: nil) —

      the metadata to set on the identifier

Returns:

Raises:



53
54
55
56
57
58
59
60
 
# 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) ⇒ Ezid::Identifier

Modifies the metadata of an existing identifier.

Parameters:

  • id (String) —

    the EZID identifier

  • metadata (Hash) —

    the metadata to update on the identifier

Returns:

Raises:



67
68
69
70
71
72
73
 
# 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

Instance Method Details

#client ⇒ Object 



318
319
320
 
# File 'lib/ezid/identifier.rb', line 318

def client
  @client ||= Client.new
end

#deletable? ⇒ Boolean

Is the identifier deletable?

Returns:

  • (Boolean) 


291
292
293
 
# File 'lib/ezid/identifier.rb', line 291

def deletable?
  persisted? && reserved?
end

#delete ⇒ Ezid::Identifier

Deletes the identifier from EZID

Returns:

Raises:

See Also:



262
263
264
265
266
267
268
269
 
# 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? ⇒ Boolean

Has the identifier been deleted?

Returns:

  • (Boolean) 


208
209
210
 
# File 'lib/ezid/identifier.rb', line 208

def deleted?
  !!deleted
end

#inspect ⇒ Object 



132
133
134
135
136
137
138
139
140
141
 
# 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 ⇒ Ezid::Identifier

Loads the metadata from EZID and marks the identifier as persisted.

Returns:

Raises:

  • (Ezid::Error) —

    the identifier is not found or other error.



230
231
232
233
234
235
 
# 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) ⇒ Ezid::Identifier

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.

Parameters:

Returns:

See Also:

  • BatchEnumerator
  • load


244
245
246
247
248
 
# File 'lib/ezid/identifier.rb', line 244

def load_metadata!(metadata)
  load_remote_metadata(metadata)
  persists!
  self
end

#local_metadata ⇒ Object 



157
158
159
 
# File 'lib/ezid/identifier.rb', line 157

def local_metadata
  @local_metadata ||= Metadata.new
end

#metadata(_ = nil) ⇒ Ezid::Metadata

Returns the identifier metadata

Returns:



149
150
151
152
153
154
155
 
# 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! ⇒ Ezid::Identifier

Force a modification of the EZID identifier – i.e.,

assumes previously persisted without confirmation.

Returns:

Raises:



184
185
186
187
188
189
190
 
# 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? ⇒ Boolean

Is the identifier persisted?

Returns:

  • (Boolean) 


202
203
204
 
# File 'lib/ezid/identifier.rb', line 202

def persisted?
  !!persisted
end

#public! ⇒ String

Mark the identifier as public

Returns:

  • (String) —

    the new status



314
315
316
 
# File 'lib/ezid/identifier.rb', line 314

def public!
  self.status = Status::PUBLIC
end

#public? ⇒ Boolean

Is the identifier public?

Returns:

  • (Boolean) 


279
280
281
 
# File 'lib/ezid/identifier.rb', line 279

def public?
  status == Status::PUBLIC
end

#reload ⇒ Object

Deprecated.

Use #load_metadata instead.



222
223
224
225
 
# 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 ⇒ Object 



161
162
163
 
# File 'lib/ezid/identifier.rb', line 161

def remote_metadata
  @remote_metadata ||= Metadata.new
end

#reserved? ⇒ Boolean

Is the identifier reserved?

Returns:

  • (Boolean) 


273
274
275
 
# File 'lib/ezid/identifier.rb', line 273

def reserved?
  status == Status::RESERVED
end

#reset ⇒ Ezid::Identifier

Empties the (local) metadata (changes will be lost!)

Returns:



252
253
254
255
256
 
# 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 ⇒ Object 



322
323
324
325
 
# File 'lib/ezid/identifier.rb', line 322

def reset_metadata
  local_metadata.clear
  remote_metadata.clear
end

#save ⇒ Ezid::Identifier

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.

Returns:

Raises:

  • (Ezid::Error) —

    if the identifier is deleted, or the host responds with an error status.



172
173
174
175
176
177
 
# 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 ⇒ Object 



143
144
145
 
# File 'lib/ezid/identifier.rb', line 143

def to_s
  id
end

#unavailable!(reason = nil) ⇒ String

Mark the identifier as unavailable

Parameters:

  • reason (String) (defaults to: nil) —

    an optional reason

Returns:

  • (String) —

    the new status



298
299
300
301
302
303
304
305
306
307
308
309
310
 
# 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? ⇒ Boolean

Is the identifier unavailable?

Returns:

  • (Boolean) 


285
286
287
 
# File 'lib/ezid/identifier.rb', line 285

def unavailable?
  status.to_s.start_with? Status::UNAVAILABLE
end

#update(data = {}) ⇒ Ezid::Identifier

Updates the metadata and saves the identifier

Parameters:

  • data (Hash) (defaults to: {}) —

    a hash of metadata

Returns:

Raises:



216
217
218
219
 
# File 'lib/ezid/identifier.rb', line 216

def update(data={})
  update_metadata(data)
  save
end

#update_metadata(attrs = {}) ⇒ Ezid::Identifier

Updates the metadata

Parameters:

  • attrs (Hash) (defaults to: {}) —

    the metadata

Returns:



195
196
197
198
 
# File 'lib/ezid/identifier.rb', line 195

def update_metadata(attrs={})
  local_metadata.update(attrs)
  self
end