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
 
# File 'lib/ezid/identifier.rb', line 87

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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(*args) ⇒ Object (protected) 



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

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:



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

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
 
# 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 



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

def client
  @client ||= Client.new
end

#deletable? ⇒ Boolean

Is the identifier deletable?

Returns:

  • (Boolean) 


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

def deletable?
  persisted? && reserved?
end

#delete ⇒ Ezid::Identifier

Deletes the identifier from EZID

Returns:

Raises:

See Also:



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

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) 


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

def deleted?
  !!deleted
end

#inspect ⇒ Object 



105
106
107
108
109
110
111
112
113
114
 
# File 'lib/ezid/identifier.rb', line 105

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

Returns:

Raises:



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

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

Returns:



122
123
124
125
126
127
 
# File 'lib/ezid/identifier.rb', line 122

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.

Returns:

Raises:



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

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) 


170
171
172
 
# File 'lib/ezid/identifier.rb', line 170

def persisted?
  !!persisted
end

#public! ⇒ String

Mark the identifier as public

Returns:

  • (String) —

    the new status



270
271
272
 
# File 'lib/ezid/identifier.rb', line 270

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

#public? ⇒ Boolean

Is the identifier public?

Returns:

  • (Boolean) 


235
236
237
 
# File 'lib/ezid/identifier.rb', line 235

def public?
  status == Status::PUBLIC
end

#reload ⇒ Object

Deprecated.

Use #load_metadata instead.



190
191
192
193
 
# File 'lib/ezid/identifier.rb', line 190

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 



129
130
131
 
# File 'lib/ezid/identifier.rb', line 129

def remote_metadata
  @remote_metadata ||= Metadata.new
end

#reserved? ⇒ Boolean

Is the identifier reserved?

Returns:

  • (Boolean) 


229
230
231
 
# File 'lib/ezid/identifier.rb', line 229

def reserved?
  status == Status::RESERVED
end

#reset ⇒ Ezid::Identifier

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

Returns:



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

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 



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

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.

Returns:

Raises:

  • (Ezid::Error) —

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



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

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

#to_s ⇒ Object 



116
117
118
 
# File 'lib/ezid/identifier.rb', line 116

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



254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/ezid/identifier.rb', line 254

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) 


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

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:



184
185
186
187
 
# File 'lib/ezid/identifier.rb', line 184

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

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

Updates the metadata

Parameters:

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

    the metadata

Returns:



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

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