represents an object that has the ability to 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 (a) have a URL, (b) can be created, updated,
deleted, or retrieved, and (c) 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 = '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"` by default). 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 an anonymous object containing the
object's attributes. In (very) rare instances, the objects in the array
are named, and `json_collection_element` contains the name of the
collection objects. For example, in this:
`{"allowedDomain":[{"allowedDomain":{"name":"foo"}}]}`, then
`json_collection_element` would be set to `'allowedDomain'`.
The PersistentObject class supports the standard `Create()`, `Update()`,
and `Delete()` 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($parm=array()) { $this->NoCreate(); }
This will cause any call to the `Create()` method to fail with an
exception.
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.
Arguments
Name
Type
Description
Default
$object
n/a
this will be encoded as json, and we handle all the JSON
error-checking in one place
Return value
Type
Description
n/a
n/a
Tags
Name
Description
throws
if server ID is not defined
throws
on other errors
returns
boolean; TRUE if successful, FALSE otherwise
CheckExtension(
$alias,
)
:
n/a
Description
checks for `$alias` in extensions and throws an error if not present
Returns an object for the Create() method JSON Must be overridden in a child class.
Return value
Type
Description
n/a
n/a
Tags
Name
Description
throws
if not overridden
CreateUrl(
)
:
string
Description
returns the URL used for Create
Return value
Type
Description
string
Delete(
)
:
\OpenCloud\Common\HttpResponse
Description
Deletes an object
Return value
Type
Description
\OpenCloud\Common\HttpResponse
Tags
Name
Description
api
throws
if HTTP status is not Success
FindLink(
string
$type
= 'self',
)
:
string
Description
Since each server can have multiple links, this returns the desired one
Arguments
Name
Type
Description
Default
$type
string
'self' is most common; use 'bookmark' for
the version-independent one
'self'
Return value
Type
Description
string
the URL from the links block
Id(
)
:
string
Description
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.
Return value
Type
Description
string
Tags
Name
Description
api
JsonCollectionElement(
)
:
string
Description
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" : ... } ] }`
Return value
Type
Description
string
JsonCollectionName(
)
:
string
Description
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.
Return value
Type
Description
string
JsonName(
)
:
n/a
Description
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).
Return value
Type
Description
n/a
n/a
Tags
Name
Description
throws
if not overridden
Name(
)
:
string
Description
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.
Return value
Type
Description
string
Tags
Name
Description
api
throws
if attribute 'name' is not defined
NoCreate(
)
:
n/a
Description
throws a CreateError for subclasses that don't support Create
Return value
Type
Description
n/a
n/a
Tags
Name
Description
throws
NoDelete(
)
:
n/a
Description
throws a DeleteError for subclasses that don't support Delete
Return value
Type
Description
n/a
n/a
Tags
Name
Description
throws
NoUpdate(
)
:
n/a
Description
throws a UpdateError for subclasses that don't support Update
Return value
Type
Description
n/a
n/a
Tags
Name
Description
throws
Parent(
)
:
n/a
Description
returns the parent object of this object This is a synonym for Service(), since the object is usually a
service.
Return value
Type
Description
n/a
n/a
PrimaryKeyField(
)
:
string
Description
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.
Return value
Type
Description
string
Refresh(
$id
= null,
$url
= null,
)
:
void
Description
Refreshes the object from the origin (useful when the server is
changing states)
Arguments
Name
Type
Description
Default
$id
n/a
null
$url
n/a
null
Return value
Type
Description
void
Tags
Name
Description
throws
Region(
)
:
n/a
Description
returns the region associated with the object navigates to the parent service to determine the region.
Return value
Type
Description
n/a
n/a
Tags
Name
Description
api
ResourceName(
)
:
n/a
Description
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.
Return value
Type
Description
n/a
n/a
Tags
Name
Description
throws
Service(
)
:
n/a
Description
Returns the Service/parent object associated with this object
Return value
Type
Description
n/a
n/a
Status(
)
:
string
Description
returns the object's status or `N/A` if not available
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.
Arguments
Name
Type
Description
Default
$terminal
string
the terminal state to wait for
'ACTIVE'
$timeout
integer
the max time (in seconds) to wait
RAXSDK_SERVER_MAXTIMEOUT
$callback
callable
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
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.
Metadata The Metadata class represents either Server or Image metadata
Nova Nova is an abstraction layer for the OpenStack compute service.
ObjectStore Intermediate (abstract) class to implement shared
features of all object-storage classes
PersistentObject represents an object that has the ability to be
retrieved, created, updated, and deleted.
Service This class defines a "service"—a relationship between a specific OpenStack
and a provided service, represented by a URL in the service catalog.
ServiceCatalogItem Holds information on a single service from the Service Catalog
Curl The CurlRequest class is a simple wrapper to CURL functions. Not only does
this permit stubbing of the interface as described under the HttpRequest
interface, it could potentially allow us to replace the interface methods
with other function calls in the future.
HttpRequestInterface The HttpRequest interface defines methods for wrapping CURL; this allows
those methods to be stubbed out for unit testing, thus allowing us to
test without actually making live calls.
Response
Blank The HttpResponse returns an object with status information, separated
headers, and any response body necessary.
Http The HttpResponse returns an object with status information, separated
headers, and any response body necessary.
Compute
Flavor The Flavor class represents a flavor defined by the Compute service
Image The Image class represents a stored machine image returned by the
Compute service.
Network The Network class represents a single virtual network
Server The Server class represents a single server node.
Record The Record class represents a single domain record
Service This class defines a "service"—a relationship between a specific OpenStack
and a provided service, represented by a URL in the service catalog.
Subdomain The Subdomain is basically another domain, albeit one that is a child of
a parent domain. In terms of the code involved, the JSON is slightly
different than a top-level domain, and the parent is a domain instead of
the DNS service itself.
Database
Database This class represents a Database in the Rackspace "Red Dwarf"
database-as-a-service product.
Instance Instance represents an instance of DbService, similar to a Server in a
Compute service
Service The Rackspace Database As A Service (aka "Red Dwarf")
User This class represents a User in the Rackspace "Red Dwarf"
database-as-a-service product.
LoadBalancer
Algorithm sub-resource to manage algorithms (read-only)
AllowedDomain sub-resource to manage allowed domains
BillableLoadBalancer used to get a list of billable load balancers for a specific date range
LoadBalancer The LoadBalancer class represents a single load balancer
Protocol sub-resource to manage protocols (read-only)
Node information on a single node in the load balancer
NodeEvent a single node event, usually called as part of a Collection
Readonly This defines a read-only SubResource - one that cannot be created, updated,
or deleted. Many subresources are like this, and this simplifies their
class definitions.
Stats Stats returns statistics about the load balancer
SubResource SubResource is an abstract class that handles subresources of a
LoadBalancer object; for example, the
`/loadbalancers/{id}/errorpage`. Since most of the subresources are
handled in a similar manner, this consolidates the functions.
Curl The CurlRequest class is a simple wrapper to CURL functions. Not only does
this permit stubbing of the interface as described under the HttpRequest
interface, it could potentially allow us to replace the interface methods
with other function calls in the future.
DataObject A DataObject is an object in the ObjectStore
Database This class represents a Database in the Rackspace "Red Dwarf"
database-as-a-service product.
HttpRequestInterface The HttpRequest interface defines methods for wrapping CURL; this allows
those methods to be stubbed out for unit testing, thus allowing us to
test without actually making live calls.
Rackspace Rackspace extends the OpenStack class with support for Rackspace's
API key and tenant requirements.
Readonly This defines a read-only SubResource - one that cannot be created, updated,
or deleted. Many subresources are like this, and this simplifies their
class definitions.
Service This class defines a "service"—a relationship between a specific OpenStack
and a provided service, represented by a URL in the service catalog.
Service The Compute class represents the OpenStack Nova service.
Service The Rackspace Database As A Service (aka "Red Dwarf")
Service This class defines a "service"—a relationship between a specific OpenStack
and a provided service, represented by a URL in the service catalog.
Stack The Stack class requires a CloudFormation template and may contain additional
parameters for that template.
Stats Stats returns statistics about the load balancer
SubResource SubResource is an abstract class that handles subresources of a
LoadBalancer object; for example, the
`/loadbalancers/{id}/errorpage`. Since most of the subresources are
handled in a similar manner, this consolidates the functions.
Subdomain The Subdomain is basically another domain, albeit one that is a child of
a parent domain. In terms of the code involved, the JSON is slightly
different than a top-level domain, and the parent is a domain instead of
the DNS service itself.
