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) 


87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/ezid/identifier.rb', line 87

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) 



296
297
298
299
300
 
# File 'lib/ezid/identifier.rb', line 296

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:

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

Raises:



78
79
80
81
82
 
# File 'lib/ezid/identifier.rb', line 78

def find(id)
  i = allocate
  i.id = id
  i.load_metadata
end

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

Mints a new identifier

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.

Raises:



67
68
69
70
71
72
 
# File 'lib/ezid/identifier.rb', line 67

def modify(id, metadata)
  i = allocate
  i.id = id
  i.update_metadata(metadata)
  i.modify!
end

Instance Method Details

#client ⇒ Object 



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

def client
  @client ||= Client.new
end

#deletable? ⇒ Boolean

Is the identifier deletable?



258
259
260
 
# File 'lib/ezid/identifier.rb', line 258

def deletable?
  persisted? && reserved?
end

#delete ⇒ Ezid::Identifier

Deletes the identifier from EZID

Raises:

See Also:



229
230
231
232
233
234
235
236
 
# File 'lib/ezid/identifier.rb', line 229

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?



187
188
189
 
# File 'lib/ezid/identifier.rb', line 187

def deleted?
  !!deleted
end

#inspect ⇒ Object 



116
117
118
119
120
121
122
123
124
125
 
# File 'lib/ezid/identifier.rb', line 116

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

Raises:



209
210
211
212
213
214
215
 
# File 'lib/ezid/identifier.rb', line 209

def load_metadata
  response = client.get_identifier_metadata(id)
  # self.remote_metadata = Metadata.new(response.metadata)
  remote_metadata.replace(response.metadata)
  persists!
  self
end

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

Returns the identifier metadata



133
134
135
136
137
138
 
# File 'lib/ezid/identifier.rb', line 133

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

#modify! ⇒ Ezid::Identifier

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

assumes previously persisted without confirmation.

Raises:



163
164
165
166
167
168
169
 
# File 'lib/ezid/identifier.rb', line 163

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?



181
182
183
 
# File 'lib/ezid/identifier.rb', line 181

def persisted?
  !!persisted
end

#public! ⇒ String

Mark the identifier as public



281
282
283
 
# File 'lib/ezid/identifier.rb', line 281

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

#public? ⇒ Boolean

Is the identifier public?



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

def public?
  status == Status::PUBLIC
end

#reload ⇒ Object

Deprecated.

Use #load_metadata instead.



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

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 



140
141
142
 
# File 'lib/ezid/identifier.rb', line 140

def remote_metadata
  @remote_metadata ||= Metadata.new
end

#reserved? ⇒ Boolean

Is the identifier reserved?



240
241
242
 
# File 'lib/ezid/identifier.rb', line 240

def reserved?
  status == Status::RESERVED
end

#reset ⇒ Ezid::Identifier

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



219
220
221
222
223
 
# File 'lib/ezid/identifier.rb', line 219

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 



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

def reset_metadata
  metadata.clear unless metadata.empty?
  remote_metadata.clear unless remote_metadata.empty?
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.

Raises:

  • (Ezid::Error) —

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



151
152
153
154
155
156
 
# File 'lib/ezid/identifier.rb', line 151

def save
  raise Error, "Cannot save a deleted identifier." if deleted?
  persist
  reset_metadata
  self
end

#to_s ⇒ Object 



127
128
129
 
# File 'lib/ezid/identifier.rb', line 127

def to_s
  id
end

#unavailable!(reason = nil) ⇒ String

Mark the identifier as unavailable



265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/ezid/identifier.rb', line 265

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?



252
253
254
 
# File 'lib/ezid/identifier.rb', line 252

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

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

Updates the metadata and saves the identifier

Raises:



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

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

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

Updates the metadata



174
175
176
177
 
# File 'lib/ezid/identifier.rb', line 174

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