Documentation

Queue extends PersistentResource
in package

Application

A queue holds messages. Ideally, a queue is created per work type. For example, if you want to compress files, you would create a queue dedicated to this job.

Any application that reads from this queue would only compress files.

MAX_POST_MESSAGES = 10: Maximum number of messages that can be posted at once.
PATCH_CONTENT_TYPE = OpenCloudCommonConstantsMime::JSON_PATCH
$createKeys : mixed
$aliases : array<string|int, mixed>: The aliases configure for the properties of the instance.
$json_collection_name : mixed
$json_name : mixed
$metadata : array<string|int, mixed>|Metadata: Miscellaneous, user-defined information about the queue.
$parent : BaseResource
$service : ServiceInterface
$url_resource : mixed
$href : string: Populated when the service's listQueues() method is called. Provides a convenient link for a particular Queue.md.
$logger : LoggerInterface: The logger instance
$name : string: The name given to the queue. The name MUST NOT exceed 64 bytes in length, and is limited to US-ASCII letters, digits, underscores, and hyphens.
$properties : array<string|int, mixed>: Holds all the properties added by overloading.
__call() : mixed: Intercept non-existent method calls for dynamic getter/setter functionality.
__construct() : mixed
checkExtension() : bool: Check whether an extension is valid
checkJsonError() : mixed: Checks the most recent JSON operation for errors.
claimMessages() : mixed: This operation claims a set of messages, up to limit, from oldest to newest, skipping any that are already claimed. If no unclaimed messages are available, FALSE is returned.
create() : Response: Create a new resource
createJson() : object: Provides JSON for create request body
createMessage() : bool: Post an individual message.
createMessages() : bool: Post multiple messages.
createUrl() : Url
delete() : Response: Delete this resource
deleteMessages() : bool: This operation immediately deletes the specified messages, providing a means for bulk deletes.
findLink() : bool: Find a resource link based on a type
generateUuid() : mixed
getClaim() : Claim: If an ID is supplied, the API is queried for a persistent object; otherwise an empty object is returned.
getClient() : ClientInterface: Convenience method to return the service's client
getInstance() : static
getLogger() : LoggerInterface: Returns the Logger object.
getMessage() : Message: Gets a message either by a specific ID, or, if no ID is specified, just an empty Message object.
getMetadata() : Metadata
getName() : string
getParent() : mixed
getService() : ServiceInterface
getStats() : object: This operation returns queue statistics including how many messages are in the queue, broken out by status.
getUrl() : mixed: Get this resource's URL
hasLogger() : bool
id() : mixed
jsonCollectionElement() : string: Returns the nested keys that could (rarely) prefix collection items. For example:
jsonCollectionName() : string: Returns the top-level key for collection responses
jsonName() : mixed: Returns the top-level key for the returned response JSON document
listMessages() : MessageIterator: Lists messages according to certain filter options. Results are ordered by age, oldest message first. All of the parameters are optional.
makeResourceIteratorOptions() : mixed
name() : string
parseResponse() : mixed: Parse a HTTP response for the required content
populate() : mixed: Populates the current object based on an unknown data type.
primaryKeyField() : mixed
refresh() : Response: Refresh the state of a resource
refreshFromLocationUrl() : mixed: Given a `location` URL, refresh this resource
region() : mixed
resourceName() : mixed: Returns the URI path for this resource
retrieveMetadata() : mixed: Retrieve metadata from the API and set it to the local object.
saveMetadata() : mixed: Save this metadata both to the local object and the API.
setLogger() : $this: Sets the logger.
setMetadata() : $this
setName() : $this: Set the name (with validation).
setParent() : self
setService() : PersistentObject
status() : string
stripNamespace() : mixed
toCamel() : mixed: Convert a string to camelCase format.
toUnderscores() : mixed: Convert string to underscore format.
update() : Response: Update a resource
url() : mixed
waitFor() : mixed: A method to repeatedly poll the API resource, waiting for an eventual state change
generateJsonPatch() : string: Generates a JSON Patch representation and return its
getAlias() : string: Returns the alias configured for the given key. If no alias exists it returns the original key.
getJsonHeader() : mixed
getPatchHeaders() : mixed
getProperty() : mixed: Grab value out of the data array.
getUpdateablePropertiesAsArray() : mixed: Returns the object's properties as an array
noCreate() : mixed
noDelete() : mixed
noUpdate() : mixed
propertyExists() : bool: Basic check to see whether property exists.
recursivelyAliasPropertyValue() : mixed: Returns the given property value's alias, if configured; Else, the unchanged property value is returned. If the given property value is an array or an instance of \stdClass, it is aliases recursively.
refreshFromParent() : mixed: Causes resource to refresh based on parent's URL
setProperty() : mixed: We can set a property under three conditions:
updateJson() : mixed: Provides JSON for update request body
checkAttributePrefix() : bool: Checks the attribute $property and only permits it if the prefix is in the specified $prefixes array
isAccessible() : bool: Does the property exist in the object variable list (i.e. does it have public or protected visibility?)

MAX_POST_MESSAGES

Maximum number of messages that can be posted at once.


    public
    mixed
    MAX_POST_MESSAGES
    = 10

PATCH_CONTENT_TYPE


    public
    mixed
    PATCH_CONTENT_TYPE
    = OpenCloudCommonConstantsMime::JSON_PATCH

$createKeys


    public
        mixed
    $createKeys
     = array('name')

$aliases

The aliases configure for the properties of the instance.


    protected
        array<string|int, mixed>
    $aliases
     = array()

$json_collection_name


    protected
    static    mixed
    $json_collection_name
     = 'queues'

$json_name


    protected
    static    mixed
    $json_name
     = false

$metadata

Miscellaneous, user-defined information about the queue.


    protected
        array<string|int, mixed>|Metadata
    $metadata

$parent


    protected
        BaseResource
    $parent

$service


    protected
        ServiceInterface
    $service

$url_resource


    protected
    static    mixed
    $url_resource
     = 'queues'

$href

Populated when the service's listQueues() method is called. Provides a convenient link for a particular Queue.md.


    private
        string
    $href

$logger

The logger instance


    private
        LoggerInterface
    $logger

$name

The name given to the queue. The name MUST NOT exceed 64 bytes in length, and is limited to US-ASCII letters, digits, underscores, and hyphens.


    private
        string
    $name

$properties

Holds all the properties added by overloading.


    private
        array<string|int, mixed>
    $properties
     = array()

__call()

Intercept non-existent method calls for dynamic getter/setter functionality.


    public
                __call( $method,  $args) : mixed

Parameters

$method :
$args :

Return values

mixed —

__construct()


    public
                __construct(ServiceInterface $service[,  $data = null ]) : mixed

Parameters

$service : ServiceInterface: The service that this resource belongs to
$data : = null: $data

Return values

mixed —

checkExtension()

Check whether an extension is valid


    public
                checkExtension(mixed $alias) : bool

Parameters

$alias : mixed: The extension name

Return values

bool —

checkJsonError()

Checks the most recent JSON operation for errors.


    public
            static    checkJsonError() : mixed

Return values

mixed —

claimMessages()

This operation claims a set of messages, up to limit, from oldest to newest, skipping any that are already claimed. If no unclaimed messages are available, FALSE is returned.


    public
                claimMessages([array<string|int, mixed> $options = array() ]) : mixed

You should delete the message when you have finished processing it, before the claim expires, to ensure the message is processed only once. Be aware that you must call the delete() method on the Message object and pass in the Claim ID, rather than relying on the service's bulk delete deleteMessages() method. This is so that the server can return an error if the claim just expired, giving you a chance to roll back your processing of the given message, since another worker will likely claim the message and process it.

Just as with a message's age, the age given for the claim is relative to the server's clock, and is useful for determining how quickly messages are getting processed, and whether a given message's claim is about to expire.

When a claim expires, it is removed, allowing another client worker to claim the message in the case that the original worker fails to process it.

Parameters

$options : array<string|int, mixed> = array()

Return values

mixed —

create()

Create a new resource


    public
                create([mixed $params = array() ]) : Response

Parameters

$params : mixed = array()

Return values

Response —

createJson()

Provides JSON for create request body


    public
                createJson() : object

Return values

object —

createMessage()

Post an individual message.


    public
                createMessage(array<string|int, mixed> $params) : bool

Parameters

$params : array<string|int, mixed>

Return values

bool —

createMessages()

Post multiple messages.


    public
                createMessages(array<string|int, mixed> $messages) : bool

Parameters

$messages : array<string|int, mixed>

Return values

bool —

createUrl()


    public
                createUrl() : Url

Return values

Url —

delete()

Delete this resource


    public
                delete() : Response

Return values

Response —

deleteMessages()

This operation immediately deletes the specified messages, providing a means for bulk deletes.


    public
                deleteMessages(array<string|int, mixed> $ids) : bool

Parameters

$ids : array<string|int, mixed>: Two-dimensional array of IDs to be deleted

Return values

bool —

findLink()

Find a resource link based on a type


    public
                findLink([string $type = 'self' ]) : bool

Parameters

$type : string = 'self'

Return values

bool —

generateUuid()


    public
            static    generateUuid() : mixed

Return values

mixed —

getClaim()

If an ID is supplied, the API is queried for a persistent object; otherwise an empty object is returned.


    public
                getClaim([int $id = null ]) : Claim

Parameters

$id : int = null

Return values

Claim —

getClient()

Convenience method to return the service's client


    public
                getClient() : ClientInterface

Return values

ClientInterface —

getInstance()


    public
            static    getInstance() : static

Return values

static —

getLogger()

Returns the Logger object.


    public
                getLogger() : LoggerInterface

Return values

LoggerInterface —

getMessage()

Gets a message either by a specific ID, or, if no ID is specified, just an empty Message object.


    public
                getMessage([string|null $id = null ]) : Message

Parameters

$id : string|null = null: If a string, then the service will retrieve an individual message based on its specific ID. If NULL, then an empty object is returned for further use.

Return values

Message —

getMetadata()


    public
                getMetadata() : Metadata

Return values

Metadata —

getName()


    public
                getName() : string

Return values

string —

getParent()


    public
                getParent() : mixed

Return values

mixed —

getService()


    public
                getService() : ServiceInterface

Return values

ServiceInterface —

getStats()

This operation returns queue statistics including how many messages are in the queue, broken out by status.


    public
                getStats() : object

Return values

object —

getUrl()

Get this resource's URL


    public
                getUrl([null $path = null ][, array<string|int, mixed> $query = array() ]) : mixed

Parameters

$path : null = null: URI path to add on
$query : array<string|int, mixed> = array(): Query to add on

Return values

mixed —

hasLogger()


    public
                hasLogger() : bool

Return values

bool —

id()


    public
                id() : mixed

Return values

mixed —

jsonCollectionElement()

Returns the nested keys that could (rarely) prefix collection items. For example:


    public
            static    jsonCollectionElement() : string

{ "keypairs": [ { "keypair": { "fingerprint": "...", "name": "key1", "public_key": "..." } }, { "keypair": { "fingerprint": "...", "name": "key2", "public_key": "..." } } ] }

In the above example, "keypairs" would be the $json_collection_name and "keypair" would be the $json_collection_element

Return values

string —

jsonCollectionName()

Returns the top-level key for collection responses


    public
            static    jsonCollectionName() : string

Return values

string —

jsonName()

Returns the top-level key for the returned response JSON document


    public
            static    jsonName() : mixed

Return values

mixed —

listMessages()

Lists messages according to certain filter options. Results are ordered by age, oldest message first. All of the parameters are optional.


    public
                listMessages([array<string|int, mixed> $options = array() ]) : MessageIterator

Parameters

$options : array<string|int, mixed> = array()

An associative array of filtering parameters:

ids (array) A two-dimensional array of IDs to retrieve.
claim_id (string) The claim ID to which the message is associated.
marker (string) An opaque string that the client can use to request the next batch of messages. If not specified, the API will return all messages at the head of the queue (up to limit).
limit (integer) A number up to 20 (the default, but is configurable) queues to return. If not specified, it defaults to 10.
echo (bool) Determines whether the API returns a client's own messages, as determined by the uuid portion of the User-Agent header. If not specified, echo defaults to FALSE.
include_claimed (bool) Determines whether the API returns claimed messages as well as unclaimed messages. If not specified, defaults to FALSE (i.e. only unclaimed messages are returned).

Return values

MessageIterator —

makeResourceIteratorOptions()


    public
                makeResourceIteratorOptions(mixed $resource) : mixed

Parameters

$resource : mixed

Return values

mixed —

name()


    public
                name() : string

Return values

string —

parseResponse()

Parse a HTTP response for the required content


    public
                parseResponse(Response $response) : mixed

Parameters

$response : Response

Return values

mixed —

populate()

Populates the current object based on an unknown data type.


    public
                populate(mixed $info[, mixed $setObjects = true ]) : mixed

Parameters

$info : mixed
$setObjects : mixed = true

Return values

mixed —

primaryKeyField()


    public
                primaryKeyField() : mixed

Return values

mixed —

refresh()

Refresh the state of a resource


    public
                refresh([null $id = null ][, null $url = null ]) : Response

Parameters

$id : null = null
$url : null = null

Return values

Response —

refreshFromLocationUrl()

Given a `location` URL, refresh this resource


    public
                refreshFromLocationUrl( $url) : mixed

Parameters

$url :

Return values

mixed —

region()


    public
                region() : mixed

Return values

mixed —

resourceName()

Returns the URI path for this resource


    public
            static    resourceName() : mixed

Return values

mixed —

retrieveMetadata()

Retrieve metadata from the API and set it to the local object.


    public
                retrieveMetadata() : mixed

Return values

mixed —

saveMetadata()

Save this metadata both to the local object and the API.


    public
                saveMetadata([array<string|int, mixed> $params = array() ]) : mixed

Parameters

$params : array<string|int, mixed> = array()

Return values

mixed —

setLogger()

Sets the logger.


    public
                setLogger([LoggerInterface $logger = null ]) : $this

Parameters

$logger : LoggerInterface = null

Return values

$this —

setMetadata()


    public
                setMetadata(mixed $data) : $this

Parameters

$data : mixed

Return values

$this —

setName()

Set the name (with validation).


    public
                setName( $name) : $this

Parameters

$name :: string

Return values

$this —

setParent()


    public
                setParent(BaseResource $parent) : self

Parameters

$parent : BaseResource

Return values

self —

setService()


    public
                setService(ServiceInterface $service) : PersistentObject

Parameters

$service : ServiceInterface

Return values

PersistentObject —

status()


    public
                status() : string

Return values

string —

stripNamespace()


    public
                stripNamespace(mixed $namespace) : mixed

Parameters

$namespace : mixed

Return values

mixed —

toCamel()

Convert a string to camelCase format.


    public
                toCamel( $string[, bool $capitalise = true ]) : mixed

Parameters

$string :
$capitalise : bool = true: Optional flag which allows for word capitalization.

Return values

mixed —

toUnderscores()

Convert string to underscore format.


    public
                toUnderscores( $string) : mixed

Parameters

$string :

Return values

mixed —

update()

Update a resource


    public
                update([mixed $params = array() ]) : Response

Parameters

$params : mixed = array()

Return values

Response —

url()


    public
                url([mixed $path = null ][, array<string|int, mixed> $query = array() ]) : mixed

Parameters

$path : mixed = null
$query : array<string|int, mixed> = array()

Return values

mixed —

waitFor()

A method to repeatedly poll the API resource, waiting for an eventual state change


    public
                waitFor([null $state = null ][, null $timeout = null ][, null $callback = null ][, null $interval = null ]) : mixed

Parameters

$state : null = null: The expected state of the resource
$timeout : null = null: The maximum timeout to wait
$callback : null = null: The callback to use to check the state
$interval : null = null: How long between each refresh request

Return values

mixed —

generateJsonPatch()

Generates a JSON Patch representation and return its


    protected
                generateJsonPatch(mixed $updatedProperties) : string

Parameters

$updatedProperties : mixed: Properties of the resource to update

Return values

string —

JSON Patch representation for updates

getAlias()

Returns the alias configured for the given key. If no alias exists it returns the original key.


    protected
                getAlias(string $key) : string

Parameters

$key : string

Return values

string —

getJsonHeader()


    protected
            static    getJsonHeader() : mixed

Return values

mixed —

getPatchHeaders()


    protected
            static    getPatchHeaders() : mixed

Return values

mixed —

getProperty()

Grab value out of the data array.


    protected
                getProperty(string $property) : mixed

Parameters

$property : string

Return values

mixed —

getUpdateablePropertiesAsArray()

Returns the object's properties as an array


    protected
                getUpdateablePropertiesAsArray() : mixed

Return values

mixed —

noCreate()


    protected
                noCreate() : mixed

Return values

mixed —

noDelete()


    protected
                noDelete() : mixed

Return values

mixed —

noUpdate()


    protected
                noUpdate() : mixed

Return values

mixed —

propertyExists()

Basic check to see whether property exists.


    protected
                propertyExists(string $property[, bool $allowRetry = true ]) : bool

Parameters

$property : string: The property name being investigated.
$allowRetry : bool = true: If set to TRUE, the check will try to format the name in underscores because there are sometimes discrepancies between camelCaseNames and underscore_names.

Return values

bool —

recursivelyAliasPropertyValue()

Returns the given property value's alias, if configured; Else, the unchanged property value is returned. If the given property value is an array or an instance of \stdClass, it is aliases recursively.


    protected
                recursivelyAliasPropertyValue(mixed $propertyValue) : mixed

Parameters

$propertyValue : mixed: Array or \stdClass instance to alias

Return values

mixed —

Property value, aliased recursively

refreshFromParent()

Causes resource to refresh based on parent's URL


    protected
                refreshFromParent() : mixed

Return values

mixed —

setProperty()

We can set a property under three conditions:


    protected
                setProperty(mixed $property, mixed $value) : mixed

If it has a concrete setter: setProperty()
If the property exists
If the property name's prefix is in an approved list

Parameters

$property : mixed
$value : mixed

Return values

mixed —

updateJson()

Provides JSON for update request body


    protected
                updateJson([mixed $params = array() ]) : mixed

Parameters

$params : mixed = array()

Return values

mixed —

checkAttributePrefix()

Checks the attribute $property and only permits it if the prefix is in the specified $prefixes array


    private
                checkAttributePrefix(string $property) : bool

This is to support extension namespaces in some services.

Parameters

$property : string: the name of the attribute

Return values

bool —

isAccessible()

Does the property exist in the object variable list (i.e. does it have public or protected visibility?)


    private
                isAccessible( $property) : bool

Parameters

$property :

Return values

bool —