Overview

Namespaces

  • None
  • OpenCloud
    • Autoscale
      • Resource
    • CloudMonitoring
      • Exception
      • Resource
    • Common
      • Exceptions
      • Log
      • Request
        • Response
    • Compute
    • Database
    • DNS
    • LoadBalancer
      • Resources
    • ObjectStore
      • Resource
    • Orchestration
    • Volume
  • PHP

Classes

  • Base
  • Collection
  • Lang
  • Metadata
  • Nova
  • PersistentObject
  • Service
  • ServiceCatalogItem
  • Overview
  • Namespace
  • Class
  • Tree
  • Download

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
Extended by OpenCloud\Common\PersistentObject

Direct known subclasses

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

Indirect known subclasses

OpenCloud\Autoscale\Resource\Group, OpenCloud\Autoscale\Resource\GroupConfiguration, OpenCloud\CloudMonitoring\Resource\Notification, OpenCloud\CloudMonitoring\Resource\NotificationPlan, OpenCloud\CloudMonitoring\Resource\ReadonlyResource, OpenCloud\DNS\Domain, OpenCloud\DNS\PtrRecord, OpenCloud\DNS\Record, OpenCloud\DNS\Subdomain, OpenCloud\LoadBalancer\Resources\Access, OpenCloud\LoadBalancer\Resources\Algorithm, OpenCloud\LoadBalancer\Resources\ConnectionLogging, OpenCloud\Autoscale\Resource\LaunchConfiguration, OpenCloud\LoadBalancer\Resources\ConnectionThrottle, OpenCloud\LoadBalancer\Resources\ContentCaching, OpenCloud\LoadBalancer\Resources\ErrorPage, OpenCloud\LoadBalancer\Resources\HealthMonitor, OpenCloud\LoadBalancer\Resources\Metadata, OpenCloud\LoadBalancer\Resources\NodeEvent, OpenCloud\LoadBalancer\Resources\Readonly, OpenCloud\LoadBalancer\Resources\SessionPersistence, OpenCloud\LoadBalancer\Resources\SSLTermination, OpenCloud\LoadBalancer\Resources\Stats, OpenCloud\Autoscale\Resource\ScalingPolicy, OpenCloud\LoadBalancer\Resources\Usage, OpenCloud\LoadBalancer\Resources\VirtualIp, OpenCloud\Autoscale\Resource\Webhook, OpenCloud\CloudMonitoring\Resource\Account, OpenCloud\CloudMonitoring\Resource\AgentToken, OpenCloud\CloudMonitoring\Resource\Alarm, OpenCloud\CloudMonitoring\Resource\Check, OpenCloud\CloudMonitoring\Resource\Entity
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
# __set( string $name, mixed $value )

Validates properties that have a namespace: prefix

Validates properties that have a namespace: prefix

If the property prefix: appears in the list of supported extension namespaces, then the property is applied to the object. Otherwise, an exception is thrown.

Parameters

$name
string
$name the name of the property
$value
mixed
$value the property's value

Throws

AttributeError

Overrides

OpenCloud\Common\Base::__set()
public
# setService( OpenCloud\Common\Service $service )

Sets the service associated with this resource object.

Sets the service associated with this resource object.

Parameters

$service
OpenCloud\Common\Service
$service
public OpenCloud\Common\Service
# 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
public OpenCloud\Common\Service
# service( )

Legacy shortcut to getService

Legacy shortcut to getService

Returns

OpenCloud\Common\Service
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 OpenCloud\Common\PersistentObject
# parent( )

Legacy shortcut to getParent

Legacy shortcut to getParent

Returns

OpenCloud\Common\PersistentObject
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

Api

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 HttpResponse
# delete( )

Deletes an object

Deletes an object

Returns

HttpResponse

Throws

DeleteError
if HTTP status is not Success

Api

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
# url( string $subresource = null, array $queryString = array() )

Returns the default URL of the object

Returns the default URL of the object

This may have to be overridden in subclasses.

Parameters

$subresource
string
$subresource optional sub-resource string
$queryString
array
$qstr optional k/v pairs for query strings

Returns

string

Throws

UrlError
if URL is not defined

Overrides

OpenCloud\Common\Base::url()
public
# waitFor( string $terminal = 'ACTIVE', integer $timeout = RAXSDK_SERVER_MAXTIMEOUT, callable $callback = NULL, mixed $sleep = RAXSDK_POLL_INTERVAL )

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.

The polling interval is set by the constant RAXSDK_POLL_INTERVAL.

The function will automatically terminate after RAXSDK_SERVER_MAXTIMEOUT seconds elapse.

Parameters

$terminal
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
$sleep

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 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

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
public boolean
# customAction( string $url, string $method = 'GET', string|array|object $body = null )

Execute a custom resource request.

Execute a custom resource request.

Parameters

$url
string
$path
$method
string
$method
$body
string|array|object
$body

Returns

boolean

Throws

OpenCloud\Common\Exceptions\InvalidArgumentError
OpenCloud\Common\Exceptions\HttpError
OpenCloud\Common\Exceptions\ServerActionError
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
protected 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
Methods inherited from OpenCloud\Common\Base
checkJsonError(), getHttpRequestObject(), getLogger(), makeQueryString(), populate(), setLogger(), setProperty()
Properties summary
protected mixed $id
#
PHP OpenCloud API API documentation generated by ApiGen 2.8.0