Class: Splunk::ReadOnlyCollection

Inherits:
Object
  • Object
show all
Extended by:
Synonyms
Includes:
Enumerable
Defined in:
lib/splunk-sdk-ruby/collection.rb

Direct Known Subclasses

Collection, InputKinds

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(service, resource, entity_class = Entity) ⇒ ReadOnlyCollection

Returns a new instance of ReadOnlyCollection.



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 32

def initialize(service, resource, entity_class=Entity)
  @service = service
  @resource = resource
  @entity_class = entity_class

  # @infinite_count declares the value used for listing all the entities
  # in a collection. It is usually -1, but some collections use 0.
  @infinite_count = -1

  # @always_fetch tells whether, when creating an entity in this collection,
  # to bother trying to parse the response and always fetch the new state
  # after the fact. This is necessary for some collections, such as users,
  # which don't return the newly created object.
  @always_fetch = false
end

Instance Attribute Details

#entity_class ⇒ Object (readonly)

The class used to represent members of this Collection.

By default this will be Entity, but many collections such as jobs will use a subclass of it (in the case of jobs, the Job class), or even another collection (ConfigurationFile in the case of configurations).

Returns: a class.



74
75
76
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 74

def entity_class
  @entity_class
end

#resource ⇒ Object (readonly)

The path after the namespace to reach this collection.

For example, for apps resource will be [“apps”, “local”].

Returns: an Array of Strings.



62
63
64
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 62

def resource
  @resource
end

#service ⇒ Object (readonly)

The service through which this Collection refers to Splunk.

Returns: a Service.



53
54
55
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 53

def service
  @service
end

Instance Method Details

#assoc(name, namespace = nil) ⇒ Object

Find the first entity in the collection with the given name.

Optionally, you may provide a namespace. If there are multiple entities visible in this collection named name, you must provide a namespace or assoc will raise an AmbiguousEntityReference error.

Returns: an Array of [name, entity] or nil if there is no matching element.



86
87
88
89
90
91
92
93
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 86

def assoc(name, namespace=nil)
  entity = fetch(name, namespace)
  if entity.nil?
    return nil
  else
    return [entity.name, entity]
  end
end

#atom_entry_to_entity(entry) ⇒ Object

Convert an Atom entry into an entity in this collection.

The Atom entry should be in the form of an entry from AtomFeed.

Returns: An object of class @entity_class.



102
103
104
105
106
107
108
109
110
111
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 102

def atom_entry_to_entity(entry)
  name = entry["title"]
  namespace = Splunk::eai_acl_to_namespace(entry["content"]["eai:acl"])

  @entity_class.new(service=@service,
                    namespace=namespace,
                    resource=@resource,
                    name=name,
                    state=entry)
end

#each(args = {}) ⇒ Object

Calls block once for each item in the collection.

The each method takes three optional arguments as well:

  • count sets the maximum number of entities to fetch (integer >= 0)

  • offset sets how many items to skip before returning items in the collection (integer >= 0)

  • page_size sets how many items at a time should be fetched from the server and processed before fetching another set

The block is called with the entity as its argument.

If the block is omitted, returns an enumerator over all members of the entity.

Example:

service = Splunk::connect(:username => 'admin', :password => 'foo')
service.loggers.each do |key, logger|
  puts logger.name + ":" + logger['level']
end



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 135

def each(args={})
  enum = Enumerator.new() do |yielder|
    count = args.fetch(:count, @infinite_count)
    offset = args.fetch(:offset, 0)
    page_size = args.fetch(:page_size, nil)

    if !page_size.nil?
      # Do pagination. Fetch page_size at a time
      current_offset = offset
      remaining_count = count
      while remaining_count > 0
        n_entities = 0
        each(:offset => current_offset,
             :count => [remaining_count, page_size].min) do |entity|
          n_entities += 1
          yielder << entity
        end

        if n_entities < page_size
          break # We've reached the end of the collection.
        else
          remaining_count -= n_entities
          current_offset += n_entities
        end
      end
    else
      # Fetch the specified range in one pass.
      response = @service.request(:resource => @resource,
                                  :query => {"count" => count.to_s,
                                             "offset" => offset.to_s})
      feed = AtomFeed.new(response.body)
      feed.entries.each() do |entry|
        entity = atom_entry_to_entity(entry)
        yielder << entity
      end
    end
  end

  if block_given?
    enum.each() { |e| yield e }
  else
    return enum
  end
end

#each_key(args = {}, &block) ⇒ Object

Identical to the each method, but the block is passed the entity’s name.



188
189
190
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 188

def each_key(args={}, &block)
  each(args).map() { |e| e.name }.each(&block)
end

#each_pair(args = {}, &block) ⇒ Object

Identical to the each method, but the block is passed both the entity’s name, and the entity.



196
197
198
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 196

def each_pair(args={}, &block)
  each(args).map() { |e| [e.name, e] }.each(&block)
end

#each_value ⇒ Object

Identical to the each method.



183
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 183

synonym "each_value", "each"

#empty? ⇒ Boolean

Returns whether there are any entities in this collection.

Returns: true or false.

Returns:

  • (Boolean) 


205
206
207
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 205

def empty?()
  return length() == 0
end

#fetch(name, namespace = nil) ⇒ Object

Fetches name from this collection.

If name does not exist, returns nil. Otherwise returns the element. If, due to wildcards in your namespace, there are two entities visible in the collection with the same name, fetch will raise an AmbiguousEntityReference error. You must specify a namespace in this case to disambiguate the fetch.



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 218

def fetch(name, namespace=nil)
  request_args = {:resource => @resource + [name]}
  if !namespace.nil?
    request_args[:namespace] = namespace
  end

  begin
    response = @service.request(request_args)
  rescue SplunkHTTPError => err
    if err.code == 404
      return nil
    else
      raise err
    end
  end

  feed = AtomFeed.new(response.body)

  if feed.entries.length > 1
    raise AmbiguousEntityReference.new("Found multiple entities with " +
                                           "name #{name}. Please specify a disambiguating namespace.")
  else
    atom_entry_to_entity(feed.entries[0])
  end
end

#has_key?(name) ⇒ Boolean

Returns whether there is an entity named name in this collection.

Returns: a boolean. Synonyms: contains?, include?, key?, member?

Returns:

  • (Boolean) 


252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 252

def has_key?(name)
  begin
    response = @service.request(:resource => @resource + [name])
    return true
  rescue SplunkHTTPError => err
    if err.code == 404
      return false
    else
      raise err
    end
  end
end

#keys ⇒ Object

Returns an Array of all entity names in the Collection.

Returns: an Array of Strings.



275
276
277
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 275

def keys()
  return values().map() { |e| e.name }
end

#length ⇒ Object

Returns the number of entities in this collection.

Returns: a nonnegative Integer. Synonyms: size.



285
286
287
288
289
290
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 285

def length()
  response = @service.request(:resource => @resource,
                              :query => {"count" => 0})
  feed = AtomFeed.new(response.body)
  return Integer(feed.metadata["totalResults"])
end

#values(args = {}) ⇒ Object

Returns an Array of the entities in this collection.

The values method takes three optional arguments:

  • count sets the maximum number of entities to fetch (integer >= 0)

  • offset sets how many items to skip before returning items in the collection (integer >= 0)

  • page_size sets how many items at a time should be fetched from the server and processed before fetching another set

Returns: an Array of @entity_class. Synonyms: list, to_a.



308
309
310
 
# File 'lib/splunk-sdk-ruby/collection.rb', line 308

def values(args={})
  each(args).to_a()
end