entitySubclass = $entitySubclass;
}
// === Accessors ===
/**
* Not implemented.
*/
protected function getSearchNamespace()
{
// (The namespace cannot presently be overridden on a per-collection basis.)
return NULL;
}
// === Operations ===
// NOTE: This method isn't called 'list' only because PHP treats 'list' as a
// pseudo-keyword and gets confused when it's used as a method name.
/**
* Lists this collection's entities, returning a list of loaded entities.
*
* By default, all items in the collection are returned. For large
* collections, it is advisable to fetch items using multiple calls with
* the paging options (i.e. 'offset' and 'count').
*
* @param array $args (optional) {
* **namespace**: (optional) {Splunk_Namespace} The namespace in which
* to list entities. Defaults to the service's namespace.
*
* **count**: (optional) The maximum number of items to return,
* or -1 to return as many as possible.
* Defaults to returning as many as possible.
* **offset**: (optional) The offset of the first item to return.
* Defaults to 0.
*
* **search**: (optional) The search expression to filter responses
* with. For example, "foo" matches any object that has
* "foo" in a substring of a field. Similarly the
* expression "field_name=field_value" matches only objects
* that have a "field_name" field with the value
* "field_value".
* **sort_dir**: (optional) The direction to sort returned items.
* Valid values:
* - "asc": Sort in ascending order.
* - "desc": Sort in descending order.
* Defaults to "asc".
* **sort_key**: (optional) The field to use for sorting.
* Defaults to "name".
* **sort_mode**: (optional) The sorting algorithm to use. Valid values:
* - "auto": If all values of the field are numbers,
* sort numerically. Otherwise, sort
* alphabetically.
* - "alpha": Sort alphabetically.
* - "alpha_case": Sort alphabetically, case-sensitive.
* - "num": Sort numerically.
* Defaults to "auto".
* }
* @return array the entities in the listing.
* @throws Splunk_IOException
*/
public function items($args=array())
{
$args = array_merge(array(
'count' => -1,
), $args);
if ($args['count'] <= 0 && $args['count'] != -1)
throw new InvalidArgumentException(
'Count must be positive or -1 (infinity).');
if ($args['count'] == -1)
$args['count'] = 0; // infinity value for the REST API
$response = $this->sendGet('', $args);
return $this->loadEntitiesFromResponse($response);
}
/**
* Returns an array of entities from the given response.
*
* @param $response
* @return array array of Splunk_Entry.
*/
private function loadEntitiesFromResponse($response)
{
$xml = new SimpleXMLElement($response->body);
$entities = array();
foreach ($xml->entry as $entry)
{
$entities[] = $this->loadEntityFromEntry($entry);
}
return $entities;
}
/**
* Returns an entity from the given entry element.
*
* @param SimpleXMLElement $entry an element.
* @return Splunk_Entry
*/
private function loadEntityFromEntry($entry)
{
return new $this->entitySubclass(
$this->service,
$this->getEntityPath($entry->title),
$entry);
}
/**
* Returns the unique entity with the specified name in this collection.
*
* @param string $name The name of the entity to search for.
* @param Splunk_Namespace|NULL $namespace
* (optional) {Splunk_Namespace} The namespace in which
* to search. Defaults to the service's namespace.
* @return Splunk_Entity
* @throws Splunk_NoSuchEntityException
* If no such entity exists.
* @throws Splunk_AmbiguousEntityNameException
* If multiple entities with the specified name
* exist in the specified namespace.
* @throws Splunk_IOException
*/
public function get($name, $namespace=NULL)
{
$this->checkName($name);
$this->checkNamespace($namespace);
try
{
$response = $this->sendGet($this->getEntityRelativePath($name), array(
'namespace' => $namespace,
'count' => 0,
));
$entities = $this->loadEntitiesFromResponse($response);
}
catch (Splunk_HttpException $e)
{
if ($e->getResponse()->status == 404)
$entities = array();
else
throw $e;
}
if (count($entities) == 0)
{
throw new Splunk_NoSuchEntityException($name);
}
else if (count($entities) == 1)
{
return $entities[0];
}
else
{
throw new Splunk_AmbiguousEntityNameException($name);
}
}
/**
* Returns a reference to the unique entity with the specified name in this
* collection. Loading of the entity is deferred until its first use.
*
* @param string $name The name of the entity to search for.
* @param Splunk_Namespace|NULL $namespace
* (optional) {Splunk_Namespace} The namespace in which
* to search. Defaults to the service's namespace.
* @return Splunk_Entity
*/
public function getReference($name, $namespace=NULL)
{
$this->checkName($name);
$this->checkNamespace($namespace);
return new $this->entitySubclass(
$this->service,
$this->getEntityPath($name),
NULL,
$namespace);
}
/**
* Creates a new entity in this collection.
*
* @param string $name The name of the entity to create.
* @param array $args (optional) Entity-specific creation arguments,
* merged with {
* **namespace**: (optional) {Splunk_Namespace} The namespace in which
* to create the entity. Defaults to the service's
* namespace.
* }
* @return Splunk_Entity
* @throws Splunk_IOException
*/
public function create($name, $args=array())
{
$this->checkName($name);
$args = array_merge(array(
'name' => $name,
), $args);
$response = $this->sendPost('', $args);
if ($response->body === '')
{
// This endpoint doesn't return the content of the new entity.
return $this->getReference($name);
}
else
{
$xml = new SimpleXMLElement($response->body);
return $this->loadEntityFromEntry($xml->entry);
}
}
/**
* Deletes an entity from this collection.
*
* @param string $name The name of the entity to delete.
* @param array $args (optional) Entity-specific deletion arguments,
* merged with {
* **namespace**: (optional) {Splunk_Namespace} The namespace in which
* to find the entity. Defaults to the service's
* namespace.
* }
* @throws Splunk_IOException
*/
public function delete($name, $args=array())
{
$this->checkName($name);
$this->sendDelete($this->getEntityRelativePath($name), $args);
}
// === Utility ===
/**
* Returns the absolute path of the child entity with the specified name.
*/
private function getEntityPath($name)
{
return $this->path . $this->getEntityRelativePath($name);
}
/**
* Returns the relative path of the child entity with the specified name.
*/
private function getEntityRelativePath($name)
{
return urlencode($name);
}
/**
* Ensures that the specified name is not NULL or empty.
*/
protected function checkName($name)
{
if ($name === NULL || $name === '')
throw new InvalidArgumentException('Invalid empty name.');
}
/**
* Ensures that the specified namespace is a Splunk_Namespace if it is
* not NULL.
*/
protected function checkNamespace($namespace)
{
// (It's not uncommon to attempt to pass an args dictionary after
// the $name argument, so perform an explicit type check to make sure
// the caller isn't trying to do this.)
if ($namespace !== NULL && !($namespace instanceof Splunk_Namespace))
throw new InvalidArgumentException(
'Namespace must be NULL or a Splunk_Namespace.');
}
}