Class PersistentObject

Represents an object that can be retrieved, created, updated and deleted.

This class abstracts much of the common functionality between:
* Nova servers; * Swift containers and objects; * DBAAS instances; * Cinder volumes; * and various other objects that: * have a URL; * can be created, updated, deleted, or retrieved; * use a standard JSON format with a top-level element followed by a child object with attributes.

In general, you can create a persistent object class by subclassing this class and defining some protected, static variables:
* $url_resource - the sub-resource value in the URL of the parent. For example, if the parent URL is http://something/parent, then setting this value to "another" would result in a URL for the persistent object of http://something/parent/another.
* $json_name - the top-level JSON object name. For example, if the persistent object is represented by {"foo": {"attr":value, ...}}, then set $json_name to "foo".
* $json_collection_name - optional; this value is the name of a collection of the persistent objects. If not provided, it defaults to json_name with an appended "s" (e.g., if json_name is "foo", then json_collection_name would be "foos"). Set this value if the collection name doesn't follow this pattern.
* $json_collection_element - the common pattern for a collection is: {"collection": [{"attr":"value",...}, {"attr":"value",...}, ...]} That is, each element of the array is a \stdClass object containing the object's attributes. In rare instances, the objects in the array are named, and json_collection_element contains the name of the collection objects. For example, in this JSON response: {"allowedDomain":[{"allowedDomain":{"name":"foo"}}]}, json_collection_element would be set to "allowedDomain".

The PersistentObject class supports the standard CRUD methods; if these are not needed (i.e. not supported by the service), the subclass should redefine these to call the noCreate, noUpdate, or noDelete methods, which will trigger an appropriate exception. For example, if an object cannot be created:
function create($params = array()) { $this->noCreate(); }

OpenCloud\Common\Base

OpenCloud\Common\PersistentObject

Direct known subclasses

OpenCloud\Autoscale\Resource\AbstractResource, OpenCloud\CloudMonitoring\Resource\AbstractResource, OpenCloud\Database\Resource\User, OpenCloud\DNS\Resource\AsyncResponse, OpenCloud\DNS\Resource\Object, OpenCloud\LoadBalancer\Resource\LoadBalancer, OpenCloud\LoadBalancer\Resource\Node, OpenCloud\LoadBalancer\Resource\SubResource, OpenCloud\Queues\Resource\Claim, OpenCloud\Queues\Resource\Message, OpenCloud\Queues\Resource\Queue, OpenCloud\Volume\Resource\Snapshot, OpenCloud\Compute\Resource\Flavor, OpenCloud\Volume\Resource\Volume, OpenCloud\Volume\Resource\VolumeType, OpenCloud\Compute\Resource\Image, OpenCloud\Compute\Resource\KeyPair, OpenCloud\Compute\Resource\Network, OpenCloud\Compute\Resource\Server, OpenCloud\Compute\Resource\VolumeAttachment, OpenCloud\Database\Resource\Database, OpenCloud\Database\Resource\Instance

Indirect known subclasses

Abstract
Namespace: OpenCloud\Common
Located at OpenCloud/Common/PersistentObject.php

Methods summary
`public`	# `__construct( mixed $service = null, mixed $info = null )` Retrieves the instance from persistent storage Retrieves the instance from persistent storage Parameters `$service` `mixed` $service The service object for this resource `$info` `mixed` $info The ID or array/object of data
`public`	# `setService( OpenCloud\Common\Service\AbstractService $service )` Sets the service associated with this resource object. Sets the service associated with this resource object. Parameters `$service` `OpenCloud\Common\Service\AbstractService` $service
`public OpenCloud\Common\Service\AbstractService`	# `getService( )` Returns the service object for this resource; required for making requests, etc. because it has direct access to the Connection. Returns the service object for this resource; required for making requests, etc. because it has direct access to the Connection. Returns `OpenCloud\Common\Service\AbstractService`
`public`	# `setParent( OpenCloud\Common\PersistentObject $parent )` Set the parent object for this resource. Set the parent object for this resource. Parameters `$parent` `OpenCloud\Common\PersistentObject` $parent
`public OpenCloud\Common\PersistentObject`	# `getParent( )` Returns the parent. Returns the parent. Returns `OpenCloud\Common\PersistentObject`
`public`	# `getClient( )`
`public`	# `setMetadata( mixed $metadata )`
`public`	# `getMetadata( )`
`public HttpResponse`	# `create( array $params = array() )` Creates a new object Creates a new object Parameters `$params` `array` $params array of values to set when creating the object Returns `HttpResponse` Throws `VolumeCreateError` if HTTP status is not Success
`public`	# `refreshFromLocationUrl( mixed $url )`
`public HttpResponse`	# `update( array $params = array() )` Updates an existing object Updates an existing object Parameters `$params` `array` $params array of values to set when updating the object Returns `HttpResponse` Throws `VolumeCreateError` if HTTP status is not Success Api
`public`	# `refresh( mixed $id = null, mixed $url = null )` Refreshes the object from the origin (useful when the server is changing states) Refreshes the object from the origin (useful when the server is changing states) Throws `IdRequiredError`
`public HttpResponse`	# `delete( )` Deletes an object Deletes an object Returns `HttpResponse` Throws `DeleteError` if HTTP status is not Success Api
`public string`	# `url( string $path = null, array $query = array() )` Returns the default URL of the object Returns the default URL of the object This may have to be overridden in subclasses. Parameters `$path` `string` $subresource optional sub-resource string `$query` `array` $qstr optional k/v pairs for query strings Returns `string`
`public`	# `getUrl( mixed $path = null, array $query = array() )` Returns the individual URL of the service/object. Returns the individual URL of the service/object. Throws `UrlError` Overrides `OpenCloud\Common\Base::getUrl()`
`public`	# `waitFor( string $state = null, integer $timeout = null, callable $callback = null, mixed $interval = null )` Waits for the server/instance status to change Waits for the server/instance status to change This function repeatedly polls the system for a change in server status. Once the status reaches the `$terminal` value (or 'ERROR'), then the function returns. Parameters `$state` `string` $terminal the terminal state to wait for `$timeout` `integer` $timeout the max time (in seconds) to wait `$callback` `callable` $callback a callback function that is invoked with each repetition of the polling sequence. This can be used, for example, to update a status display or to permit other operations to continue `$interval` Api CodeCoverageIgnore
`protected`	# `action( mixed $object )` Sends the json string to the /action resource Sends the json string to the /action resource This is used for many purposes, such as rebooting the server, setting the root password, creating images, etc. Since it can only be used on a live server, it checks for a valid ID. Parameters `$object` `mixed` $object - this will be encoded as json, and we handle all the JSON error-checking in one place Throws `ServerIdError` if server ID is not defined `ServerActionError` on other errors Returns boolean; TRUE if successful, FALSE otherwise
`protected`	# `createJson( )` Returns an object for the Create() method JSON Must be overridden in a child class. Returns an object for the Create() method JSON Must be overridden in a child class. Throws `CreateError` if not overridden
`protected`	# `updateJson( mixed $params = array() )` Returns an object for the Update() method JSON Must be overridden in a child class. Returns an object for the Update() method JSON Must be overridden in a child class. Throws `UpdateError` if not overridden
`protected`	# `noCreate( )` throws a CreateError for subclasses that don't support Create throws a CreateError for subclasses that don't support Create Throws `CreateError`
`protected`	# `noDelete( )` throws a DeleteError for subclasses that don't support Delete throws a DeleteError for subclasses that don't support Delete Throws `DeleteError`
`protected`	# `noUpdate( )` throws a UpdateError for subclasses that don't support Update throws a UpdateError for subclasses that don't support Update Throws `UpdateError`
`public string`	# `name( )` Returns the displayable name of the object Returns the displayable name of the object Can be overridden by child objects; must be overridden by child objects if the object does not have a `name` attribute defined. Returns `string` Throws `NameError` if attribute 'name' is not defined Api
`public string`	# `status( )` returns the object's status or `N/A` if not available returns the object's status or `N/A` if not available Returns `string` Api
`public string`	# `id( )` returns the object's identifier returns the object's identifier Can be overridden by a child class if the identifier is not in the `$id` property. Use of this function permits the `$id` attribute to be protected or private to prevent unauthorized overwriting for security. Returns `string` Api
`public`	# `checkExtension( mixed $alias )` checks for `$alias` in extensions and throws an error if not present checks for `$alias` in extensions and throws an error if not present Throws `UnsupportedExtensionError`
`public`	# `region( )` returns the region associated with the object returns the region associated with the object navigates to the parent service to determine the region. Api
`public string`	# `findLink( string $type = 'self' )` Since each server can have multiple links, this returns the desired one Since each server can have multiple links, this returns the desired one Parameters `$type` `string` $type - 'self' is most common; use 'bookmark' for the version-independent one Returns `string` the URL from the links block
`public string`	# `createUrl( )` returns the URL used for Create returns the URL used for Create Returns `string`
`protected string`	# `primaryKeyField( )` Returns the primary key field for the object Returns the primary key field for the object The primary key is usually 'id', but this function is provided so that (in rare cases where it is not 'id'), it can be overridden. Returns `string`
`public static`	# `jsonName( )` Returns the top-level document identifier for the returned response JSON document; must be overridden in child classes Returns the top-level document identifier for the returned response JSON document; must be overridden in child classes For example, a server document is (JSON) `{"server": ...}` and an Instance document is `{"instance": ...}` - this function must return the top level document name (either "server" or "instance", in these examples). Throws `DocumentError` if not overridden
`public static string`	# `jsonCollectionName( )` returns the collection JSON element name returns the collection JSON element name When an object is returned in a collection, it usually has a top-level object that is an array holding child objects of the object types. This static function returns the name of the top-level element. Usually, that top-level element is simply the JSON name of the resource.'s'; however, it can be overridden by specifying the $json_collection_name attribute. Returns `string`
`public static string`	# `jsonCollectionElement( )` returns the JSON name for each element in a collection returns the JSON name for each element in a collection Usually, elements in a collection are anonymous; this function, however, provides for an element level name: `{ "collection" : [ { "element" : ... } ] }` Returns `string`
`public static`	# `resourceName( )` Returns the resource name for the URL of the object; must be overridden in child classes Returns the resource name for the URL of the object; must be overridden in child classes For example, a server is `/servers/`, a database instance is `/instances/`. Must be overridden in child classes. Throws `UrlError`
`public`	# `parseResponse( Guzzle\Http\Message\Response $response )`

Methods inherited from OpenCloud\Common\Base
`__call(), checkJsonError(), generateUuid(), getLogger(), getProperty(), makeResourceIteratorOptions(), populate(), propertyExists(), setLogger(), setProperty(), stripNamespace(), toCamel(), toUnderscores()`

Properties summary
`protected mixed`	`$metadata`		#

Namespaces

Classes

Class PersistentObject

Direct known subclasses

Indirect known subclasses

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Throws

Api

Throws

Returns

Throws

Api

Parameters

Returns

Throws

Overrides

Parameters

Api

CodeCoverageIgnore

Parameters

Throws

Returns

Throws

Throws

Throws

Throws

Throws

Returns

Throws

Api

Returns

Api

Returns

Api

Throws

Api

Parameters

Returns

Returns

Returns

Throws

Returns

Returns

Throws