class Splunk::ReadOnlyCollection

Attributes

entity_class[R]

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.

resource[R]

The path after the namespace to reach this collection.

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

Returns: an Array of Strings.

service[R]

The service through which this Collection refers to Splunk.

Returns: a Service.

Public Class Methods

new(service, resource, entity_class=Entity) click to toggle source

# 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

Public Instance Methods

assoc(name, namespace=nil) click to toggle source

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.

# 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) click to toggle source

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.

# 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={}) { |e| ... } click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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() click to toggle source

Identical to the each method.

# File lib/splunk-sdk-ruby/collection.rb, line 183
synonym "each_value", "each"

empty?() click to toggle source

Returns whether there are any entities in this collection.

Returns: true or false.

# File lib/splunk-sdk-ruby/collection.rb, line 205
def empty?()
  return length() == 0
end

fetch(name, namespace=nil) click to toggle source

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.

# 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) click to toggle source

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

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

# 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() click to toggle source

Returns an Array of all entity names in the Collection.

Returns: an Array of Strings.

# File lib/splunk-sdk-ruby/collection.rb, line 275
def keys()
  return values().map() { |e| e.name }
end

length() click to toggle source

Returns the number of entities in this collection.

Returns: a nonnegative Integer. Synonyms: size.

# 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={}) click to toggle source

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.

# File lib/splunk-sdk-ruby/collection.rb, line 308
def values(args={})
  each(args).to_a()
end