Class: Wash::Entry

Inherits:
Object
  • Object
show all
Defined in:
lib/wash/entry.rb

Overview

Entry represents a common base class for Wash entries. All plugin entries should extend this class.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#name ⇒ Object

All entries have a name. Note that the name is always included in the entry’s state hash.



242
243
244
 
# File 'lib/wash/entry.rb', line 242

def name
  @name
end

Class Method Details

.attributes(attr, *attrs) ⇒ Object

attributes is a class-level tag specifying all the attributes that make sense for instances of this specific kind of entry. It will pass the specified attributes along to attr_accessor so that instances can set their values. For example, something like

Examples:

class Foo
  # Instances of Foo will be able to set the @mtime and @meta fields
  attributes :mtime, :meta

  def initialize(mtime, meta)
    @mtime = mtime
    @meta = meta
  end
end

Parameters:

  • attr (Symbol) —

    An attribute that will be set

  • attrs (Symbol) —

    More attributes that will be set



26
27
28
29
 
# File 'lib/wash/entry.rb', line 26

def attributes(attr, *attrs)
  @attributes ||= []
  @attributes += set_fields(attr, *attrs)
end

.children ⇒ Object

children returns this Entry’s child classes. It is a helper for Entry schemas, and is useful for DRY’ing up schema code when one kind of Entry’s children matches another kind of Entry’s children.

Examples:

class VolumeDir
  parent_of 'VolumeDir', 'VolumeFile'
end

class Volume
  parent_of *VolumeDir.children
end



169
170
171
 
# File 'lib/wash/entry.rb', line 169

def children
  @child_klasses
end

.description(description) ⇒ Object

description is a class-level tag specifying the entry’s description. It is a helper for Entry schemas.

Parameters:

  • description —

    The description.



107
108
109
 
# File 'lib/wash/entry.rb', line 107

def description(description)
  @description = description
end

.is_singleton ⇒ Object

is_singleton is a class-level tag indicating that the given Entry’s a singleton. It is a helper for Entry schemas.

Note that if an Entry has the is_singleton tag and its name is not filled-in when that Entry is listed, then the Entry’s name will be set to the specified label. This means that plugin authors do not have to set singleton entries’ names, and it also enforces the convention that singleton entries’ labels should match their names.

Examples:

class Foo
  label 'foo'
  # If Foo's instance does not set @name, then the gem will set @name to 'foo'
  is_singleton
end



99
100
101
 
# File 'lib/wash/entry.rb', line 99

def is_singleton
  @singleton = true
end

.label(lbl) ⇒ Object

label is a class-level tag specifying the entry’s label. It is a helper for Entry schemas.

Parameters:

  • lbl —

    The label.



80
81
82
 
# File 'lib/wash/entry.rb', line 80

def label(lbl)
  @label = lbl
end

.meta_attribute_schema(schema) ⇒ Object

meta_attribute_schema sets the meta attribute’s schema to schema. It is a helper for Entry schemas.

Parameters:

  • schema —

    A hash containing the meta attribute’s JSON schema



127
128
129
 
# File 'lib/wash/entry.rb', line 127

def meta_attribute_schema(schema)
  @meta_attribute_schema = schema
end

.metadata_schema(schema) ⇒ Object

metadata_schema sets the metadata schema to schema. It is a helper for Entry schemas.

Parameters:

  • schema —

    A hash containing the metadata’s JSON schema



134
135
136
 
# File 'lib/wash/entry.rb', line 134

def metadata_schema(schema)
  @metadata_schema = schema
end

.parent_of(child_klass, *child_klasses) ⇒ Object

parent_of indicates that this kind of Entry is the parent of the given child classes (i.e. child entries). It is a helper for Entry schemas.

Examples:

class Foo
  # This indicates that Foo#list will return instances of Bar and Baz. Note
  # that both direct class constants (Bar) and strings ('Baz') are valid
  # input. The latter's useful when the child class is loaded after the
  # parent.
  parent_of Bar, 'Baz'
end

Parameters:

  • child_klass (Wash::Entry) —

    A child class object.

  • child_klasses (Wash::Entry) —

    More child class objects.



152
153
154
155
 
# File 'lib/wash/entry.rb', line 152

def parent_of(child_klass, *child_klasses)
  @child_klasses ||= []
  @child_klasses += [child_klass] + child_klasses
end

.signal(name, description) ⇒ Object

signal adds the given signal to the entry’s list of supported signals. It is a helper for Entry schemas.



113
114
115
 
# File 'lib/wash/entry.rb', line 113

def signal(name, description)
  add_signal_schema(name, '', description)
end

.signal_group(name, regex, description) ⇒ Object

signal_group adds the given signal group to the entry’s list of supported signals. It is a helper for Entry schemas.



119
120
121
 
# File 'lib/wash/entry.rb', line 119

def signal_group(name, regex, description)
  add_signal_schema(name, regex, description)
end

.slash_replacer(char) ⇒ Object

slash_replacer is a class-level tag that specifies the slash replacer. It should only be used if there is a chance that instances of the given class can contain a “#” in their names. Otherwise, slash_replacer should be ignored.

Examples:

class Foo
  # Tell Wash to replace all "/"es with ":" in the given Foo instance's
  # name
  slash_replacer ":"
end

Parameters:

  • char (String) —

    The slash replacer



44
45
46
 
# File 'lib/wash/entry.rb', line 44

def slash_replacer(char)
  @slash_replacer = char
end

.state(field, *fields) ⇒ Object

state is a class-level tag that specifies the minimum state required to reconstruct all instances of this specific kind of entry. Each specified state field will be passed along to attr_accessor so that instances can get/set their values.

Note that Wash.run uses Class#allocate when it reconstructs the entries, so it does not call the initialize method.

Examples:

class Foo
  # Indicates that api_key is the minimum state required to reconstruct
  # instances of Foo. The gem will serialize the api_key as part of each
  # instance's state key when passing them along to Wash. If Wash invokes
  # a method on a specific instance, then Wash.run will restore the api_key
  # prior to invoking the method (so all methods are free to directly reference
  # the @api_key field). Thus, plugin authors do not have to manage their entries'
  # states; the gem will do it for them via the state tag.
  state :api_key

  def initialize(api_key)
    @api_key = api_key
  end
end



71
72
73
74
 
# File 'lib/wash/entry.rb', line 71

def state(field, *fields)
  @state ||= []
  @state += set_fields(field, *fields)
end

Instance Method Details

#cache_ttls(ttls = {}) ⇒ Object

cache_ttls sets the cache TTLs (time-to-live) of the given methods.

Examples:

class Foo
  def initialize(content_size)
    if content_size > 10000
      # content_size > 10000 so tell Wash to cache its read result for
      # 100 seconds
      cache_ttls read: 100 
    end
  end
end

Parameters:

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

    A hash of <method_name> => <method_ttl>



328
329
330
331
 
# File 'lib/wash/entry.rb', line 328

def cache_ttls(ttls = {})
  @cache_ttls ||= {}
  @cache_ttls = @cache_ttls.merge(ttls)
end

#prefetch(method, *methods) ⇒ Object

prefetch indicates that the given methods should be prefetched. This means that the gem will invoke those methods on this particular entry instance and include their results when serializing that entry. Note that the methods are invoked during serialization.

Examples:

class Foo
  def initialize(content_size)
    if content_size < 10
      # content_size < 10, so tell the gem to invoke Foo#list and Foo#read
      # on this Foo instance during its serialization
      prefetch :list, :read
    end
  end
end

Parameters:

  • method (Symbol) —

    A method that should be prefetched.

  • methods (Symbol) —

    More methods that should be prefetched.



310
311
312
 
# File 'lib/wash/entry.rb', line 310

def prefetch(method, *methods)
  prefetched_methods.concat([method] + methods)
end

#schema ⇒ Object

schema returns the entry’s schema. It should not be overridden.



334
335
336
337
338
 
# File 'lib/wash/entry.rb', line 334

def schema
  schemaHash = {}
  self.class.send(:schema, schemaHash)
  schemaHash
end

#to_json ⇒ Object 



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/wash/entry.rb', line 244

def to_json(*)
  unless @name && @name.size > 0
    unless singleton
      raise "A nameless entry is being serialized. The entry is an instance of #{type_id}"
    end
    @name = label
  end

  hash = {
    type_id: type_id,
    name: @name,
  }

  # Include the methods
  hash[:methods] = self.class.send(:methods).map do |method|
    if prefetched_methods.include?(method)
      [method, self.send(method)]
    else
      method
    end
  end

  # Include the remaining keys. Note that these checks are here to
  # ensure that we don't serialize empty keys. They're meant to save
  # some space.
  if attributes.size > 0 && (attributes_hash = to_hash(attributes))
    hash[:attributes] = attributes_hash
  end
  if cache_ttls.size > 0
    hash[:cache_ttls] = cache_ttls
  end
  if slash_replacer.size > 0
    hash[:slash_replacer] = slash_replacer
  end
  hash[:state] = to_hash(state).merge(klass: type_id, name: @name).to_json
  if Wash.send(:pretty_print?)
    JSON.pretty_generate(hash)
  else
    JSON.generate(hash)
  end
end

#type_id ⇒ Object

type_id returns the entry’s type ID, which is its fully-qualified class name.



288
289
290
 
# File 'lib/wash/entry.rb', line 288

def type_id
  self.class.send(:type_id)
end