Class: Docker::API::Resource Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/docker/api/resource.rb

Overview

This class is abstract.

Subclass and implement #reload.

Shared behaviour for the objects the daemon describes: containers, images, networks and volumes.

The Engine API returns different shapes for the same object depending on how you asked. GET /containers/json answers with Names: ["/web"]; GET /containers/{id}/json answers with Name: "/web". A client that simply exposes whichever payload it happened to receive pushes that difference onto every caller, which is why code written against such a client ends up reading info["Names"] in one place and [:Name] in another and breaking when the two are swapped.

Resources here normalise. #name answers the same thing regardless of origin, and an object built from a list marks itself #partial?: the first accessor that needs detail the list did not carry fetches it once, rather than returning nil and letting the caller guess why.

Direct Known Subclasses

Container, Image, Network, Volume

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:, raw:, partial: false) ⇒ Resource

Returns a new instance of Resource.

Parameters:

  • client (Docker::API::Client) —

    the client to issue further calls on

  • raw (Hash) —

    the daemon's payload

  • partial (Boolean) (defaults to: false) —

    whether the payload came from a list endpoint



32
33
34
35
36
37
38
 
# File 'lib/docker/api/resource.rb', line 32

def initialize(client:, raw:, partial: false)
  @client = client
  @raw = raw || {}
  @partial = partial
  @reloaded = false
  @stale = false
end

Instance Attribute Details

#client ⇒ Docker::API::Client (readonly)

Returns the client this resource came from.

Returns:



27
28
29
 
# File 'lib/docker/api/resource.rb', line 27

def client
  @client
end

#raw ⇒ Hash (readonly)

The daemon's payload, exactly as it arrived.

Always available, so nothing this gem does not model is out of reach.

Returns:

  • (Hash) 


45
46
47
 
# File 'lib/docker/api/resource.rb', line 45

def raw
  @raw
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


86
87
88
 
# File 'lib/docker/api/resource.rb', line 86

def ==(other)
  other.is_a?(self.class) && !id.nil? && id == other.id
end

#[](key) ⇒ Object?

Read a key straight from the payload, with no normalisation.

Parameters:

  • key (String) —

    a key as the daemon spells it

Returns:

  • (Object, nil) 


61
62
63
 
# File 'lib/docker/api/resource.rb', line 61

def [](key)
  raw[key]
end

#hash ⇒ Integer

Returns:

  • (Integer) 


92
93
94
 
# File 'lib/docker/api/resource.rb', line 92

def hash
  [self.class, id].hash
end

#id ⇒ String?

Returns the object's id.

Returns:

  • (String, nil) —

    the object's id



53
54
55
 
# File 'lib/docker/api/resource.rb', line 53

def id
  raw["Id"] || raw["ID"]
end

#partial? ⇒ Boolean

Returns whether this came from a list and may lack detail.

Returns:

  • (Boolean) —

    whether this came from a list and may lack detail



48
49
50
 
# File 'lib/docker/api/resource.rb', line 48

def partial?
  @partial
end

#reload ⇒ self

Re-fetch this object from the daemon.

Returns:

  • (self)

Raises:

  • (NotImplementedError) 


74
75
76
 
# File 'lib/docker/api/resource.rb', line 74

def reload
  raise NotImplementedError, "#{self.class} must implement #reload"
end

#stale? ⇒ Boolean

Returns whether an action has changed this object since the payload in hand was fetched.

Returns:

  • (Boolean) —

    whether an action has changed this object since the payload in hand was fetched



67
68
69
 
# File 'lib/docker/api/resource.rb', line 67

def stale?
  @stale
end

#to_s ⇒ String Also known as: inspect

Returns:

  • (String) 


79
80
81
 
# File 'lib/docker/api/resource.rb', line 79

def to_s
  "#<#{self.class.name} id=#{id.to_s[0, 12]}#{partial? ? " partial" : ""}>"
end