A representation of an object stored in remote Object Storage. More...

Inheritance diagram for RemoteObject:

Public Member Functions
	useCDN ($url, $sslUrl)
	Set the URL to this object in a CDN service.
	url ($cached=FALSE, $useSSL=TRUE)
	Get the URL to this object.
	contentLength ()
	Calculate the content length.
	eTag ()
	Generate an ETag for the ObjectStorage server.
	lastModified ()
	Get the modification time, as reported by the server.
	metadata ()
	Get any associated metadata.
	setHeaders ($headers)
	Set the headers.
	headers ()
	Get the HTTP headers sent by the server.
	additionalHeaders ($mergeAll=FALSE)
	filterHeaders (&$headers)
	Filter the headers.
	removeHeaders ($keys)
	Given an array of header names.
	content ()
	Get the content of this object.
	stream ($refresh=FALSE)
	Get the content of this object as a file stream.
	setCaching ($enabled)
	Enable or disable content caching.
	isCaching ()
	Indicates whether this object caches content.
	setContentVerification ($enabled)
	Enable or disable content verification (checksum/md5).
	isVerifyingContent ()
	Indicate whether this object verifies content (checksum).
	isDirty ()
	Check whether there are unsaved changes.
	refresh ($fetchContent=FALSE)
	Rebuild the local object from the remote.
Public Member Functions inherited from Object
	__construct ($name, $content=NULL, $type=NULL)
	Construct a new object for storage.
	setMetadata (array $array)
	Set the metadata.
	setName ($name)
	Override (change) the name of an object.
	name ()
	Get the name.
	setContentType ($type)
	Set the content type (MIME type) for the object.
	contentType ()
	Get the content type.
	setContent ($content, $type=NULL)
	Set the content for this object.
	setEncoding ($encoding)
	Set the encoding for a file.
	encoding ()
	Get the encoding (if any) for this object.
	setDisposition ($disposition)
	Set the content disposition.
	disposition ()
	Get the current disposition string, if any.
	setAdditionalHeaders ($headers)
	Set additional headers for storage.
	additionalHeaders ()
	Return additional headers.
	isChunked ()
	This object should be transmitted in chunks.

Static Public Member Functions
static	newFromJSON ($data, $token, $url)
	Create a new RemoteObject from JSON data.
static	newFromHeaders ($name, $headers, $token, $url, $cdnUrl=NULL, $cdnSslUrl=NULL)
	Create a new RemoteObject from HTTP headers.

Protected Member Functions
	localFileStream ()
	Transform a local copy of content into a file stream.
	fetchObject ($fetchContent=FALSE)
	Helper function for fetching an object.
	extractFromHeaders ($response)
	Extract information from HTTP headers.

Protected Attributes
	$contentLength = 0
	$etag = ''
	$lastModified = 0
	$contentVerification = TRUE
	$caching = FALSE
	$allHeaders = array()
	All headers received from a remote are stored in this array.
	$cdnUrl
	$cdnSslUrl
	$reservedHeaders
Protected Attributes inherited from Object
	$name
	The name of the object.
	$content
	The content.
	$contentType = self::DEFAULT_CONTENT_TYPE
	The content type.
	$metadata = array()
	Associative array of stored metadata.
	$contentEncoding
	$contentDisposition
	$additionalHeaders = array()
	Extension mechanism for new headers.

Additional Inherited Members
Public Attributes inherited from Object
const	DEFAULT_CONTENT_TYPE = 'application/octet-stream'

Detailed Description

A representation of an object stored in remote Object Storage.

A remote object is one whose canonical copy is stored in a remote object storage. It represents a local (and possibly partial) copy of an object. (Contrast this with HPCloud::Storage::ObjectStorage::Object)

Depending on how the object was constructed, it may or may not have a local copy of the entire contents of the file. It may only have the object's "metadata" (information such as name, type, modification date, and length of the object). Or it may have all of that in addition to the entire content of the file.

Remote objects can be modified locally. Simply modifying an object will not result in those modifications being stored on the remote server. The object must be saved (see HPCloud::Storage::ObjectStorage::Container::save()). When an object is modified so that its local contents differ from the remote stored copy, it is marked dirty (see isDirty()).

Definition at line 50 of file RemoteObject.php.

Member Function Documentation

additionalHeaders ( $mergeAll = FALSE )

Definition at line 309 of file RemoteObject.php.

References Object\$additionalHeaders, and RemoteObject\filterHeaders().

Referenced by RemoteObject\removeHeaders().

content ( )

Get the content of this object.

Since this is a proxy object, calling content() will cause the object to be fetched from the remote data storage. The result will be delivered as one large string.

The file size, content type, etag, and modification date of the object are all updated during this command, too. This accounts for the possibility that the content was modified externally between the time this object was constructed and the time this method was executed.

Be wary of using this method with large files.

Return values

string

Returns: string The contents of the file as a string.

Exceptions

\HPCloud\Transport\FileNotFoundException	when the requested content cannot be located on the remote server.
\HPCloud\Exception	when an unknown exception (usually an abnormal network condition) occurs.

Reimplemented from Object.

Definition at line 410 of file RemoteObject.php.

References $content, RemoteObject\content(), RemoteObject\fetchObject(), RemoteObject\isCaching(), RemoteObject\isVerifyingContent(), and Object\setContent().

Referenced by RemoteObject\content(), RemoteObject\contentLength(), RemoteObject\eTag(), RemoteObject\isDirty(), RemoteObject\localFileStream(), RemoteObject\refresh(), and RemoteObject\stream().

contentLength ( )

Calculate the content length.

This returns the number of bytes in a piece of content (not the number of characters). Among other things, it is used to let the remote object store know how big of an object to expect when transmitting data.

When extending this class, you should make sure to calculate the content length appropriately.

Return values

int

Returns: int The length of the content, in bytes.

Reimplemented from Object.

Definition at line 243 of file RemoteObject.php.

References RemoteObject\content().

Referenced by RemoteObject\extractFromHeaders(), and RemoteObject\localFileStream().

eTag ( )

Generate an ETag for the ObjectStorage server.

OpenStack uses ETag to pass validation data. This generates an ETag using an MD5 hash of the content.

When extending this class, generate an ETag by creating an MD5 of the entire object's content (but not the metadata or name).

Return values

string

Returns: string An MD5 value as a string of 32 hex digits (0-9a-f).

Reimplemented from Object.

Definition at line 250 of file RemoteObject.php.

References RemoteObject\content().

extractFromHeaders ( $response )

protected

Extract information from HTTP headers.

This is used internally to set object properties from headers.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: $this for the current object so it can be used in chaining methods.

Definition at line 708 of file RemoteObject.php.

References RemoteObject\contentLength(), Container\extractHeaderAttributes(), RemoteObject\lastModified(), Object\setContentType(), Object\setDisposition(), Object\setEncoding(), and Object\setMetadata().

Referenced by RemoteObject\fetchObject().

fetchObject ( $fetchContent = FALSE )

protected

Helper function for fetching an object.

Parameters

boolean $fetchContent If this is set to TRUE, a GET request will be issued, which will cause the remote host to return the object in the response body. The response body is not handled, though. If this is set to FALSE, a HEAD request is sent, and no body is returned.

Return values

HPCloud::Transport::Response

Returns: containing the object metadata and (depending on the $fetchContent flag) optionally the data.

Definition at line 675 of file RemoteObject.php.

References ObjectStorage\cdnUrl(), RemoteObject\extractFromHeaders(), ObjectStorage\token(), and ObjectStorage\url().

Referenced by RemoteObject\content(), RemoteObject\refresh(), and RemoteObject\stream().

filterHeaders ( & $headers )

Filter the headers.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: $this for the current object so it can be used in chaining methods.

Definition at line 339 of file RemoteObject.php.

References $name.

Referenced by RemoteObject\additionalHeaders().

headers ( )

Get the HTTP headers sent by the server.

Attention: EXPERT.

This returns the array of minimally processed HTTP headers that were sent from the server.

Return values

array

Returns: array An associative array of header names and values.

Definition at line 305 of file RemoteObject.php.

isCaching ( )

Indicates whether this object caches content.

Importantly, this indicates whether the object will cache its contents, not whether anything is actually cached.

Return values

boolean

Returns: boolean TRUE if caching is enabled, FALSE otherwise.

Definition at line 540 of file RemoteObject.php.

Referenced by RemoteObject\content().

isDirty ( )

Check whether there are unsaved changes.

An object is marked "dirty" if it has been altered locally in such a way that it no longer matches the remote version.

The practical definition of dirtiness, for us, is this: An object is dirty if and only if (a) it has locally buffered content AND (b) the checksum of the local content does not match the checksom of the remote content.

Not that minor differences, such as altered character encoding, may change the checksum value, and thus (correctly) mark the object as dirty.

The RemoteObject implementation does not internally check dirty markers. It is left to implementors to ensure that dirty content is written to the remote server when desired.

To replace dirty content with a clean copy, see refresh().

Definition at line 614 of file RemoteObject.php.

References RemoteObject\content().

isVerifyingContent ( )

Indicate whether this object verifies content (checksum).

When content verification is on, RemoteObject attemts to perform a checksum on the object, calculating the MD5 hash of the content returned by the remote server, and comparing that to the server's supplied ETag hash.

Return values

boolean

Returns: boolean TRUE if this is verifying, FALSE otherwise.

Definition at line 588 of file RemoteObject.php.

Referenced by RemoteObject\content().

lastModified ( )

Get the modification time, as reported by the server.

This returns an integer timestamp indicating when the server's copy of this file was last modified.

Definition at line 265 of file RemoteObject.php.

Referenced by RemoteObject\extractFromHeaders().

localFileStream ( )

protected

Transform a local copy of content into a file stream.

This buffers the content into a stream resource and then returns the stream resource. The resource is not used internally, and its data is never written back to the remote object storage.

Definition at line 494 of file RemoteObject.php.

References RemoteObject\content(), and RemoteObject\contentLength().

Referenced by RemoteObject\stream().

metadata ( )

Get any associated metadata.

This returns an associative array of all metadata for this object.

Return values

array

Returns: array An associative array of metadata. This may be empty.

Reimplemented from Object.

Definition at line 269 of file RemoteObject.php.

static newFromHeaders	(	$name,
		$headers,
		$token,
		$url,
		$cdnUrl = `NULL`,
		$cdnSslUrl = `NULL`
	)

static

Create a new RemoteObject from HTTP headers.

This is used to create objects from GET and HEAD requests, which return all of the metadata inside of the headers.

Parameters

string	$name	The name of the object.
array	$headers	An associative array of HTTP headers in the exact format documented by OpenStack's API docs.
string	$token	The current auth token (used for issuing subsequent requests).
string	$url	The URL to the object in the object storage. Used for issuing subsequent requests.
string	$cdnUrl	The URL to the CDN version of the object. Used for issuing subsequent requests. If this is set, this object may use CDN to make subsequent requests. It may also return the CDN URL when requested.
string	$cdnSslUrl	The URL to the SSL-protected CDN version of the object.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: A new RemoteObject.

Definition at line 129 of file RemoteObject.php.

References RemoteObject\$cdnSslUrl, RemoteObject\$cdnUrl, $name, $object, ObjectStorage\$token, ObjectStorage\$url, and Container\extractHeaderAttributes().

static newFromJSON	(	$data,
		$token,
		$url
	)

static

Create a new RemoteObject from JSON data.

Parameters

array	$data	The JSON data as an array.
string	$token	The authentication token.
	$url	The URL to the object on the remote server

Definition at line 83 of file RemoteObject.php.

References $object, ObjectStorage\$token, and ObjectStorage\$url.

refresh ( $fetchContent = FALSE )

Rebuild the local object from the remote.

This refetches the object from the object store and then reconstructs the present object based on the refreshed data.

WARNING: This will destroy any unsaved local changes. You can use isDirty() to determine whether or not a local change has been made.

Parameters

boolean $fetchContent If this is TRUE, the content will be downloaded as well.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: $this for the current object so it can be used in chaining methods.

Definition at line 647 of file RemoteObject.php.

References RemoteObject\content(), RemoteObject\fetchObject(), and Object\setContent().

removeHeaders ( $keys )

Given an array of header names.

This will remove the given headers from the existing headers. Both additional headers and the original headers from the server are affected here.

Note that you cannot remove metadata through this mechanism, as it is managed using the metadata() methods.

Attention: Many headers are generated automatically, such as Content-Type and Content-Length. Removing these will simply result in their being regenerated.

Parameters

array $keys The header names to be removed.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: $this for the current object so it can be used in chaining methods.

Reimplemented from Object.

Definition at line 376 of file RemoteObject.php.

References $key, and RemoteObject\additionalHeaders().

setCaching ( $enabled )

Enable or disable content caching.

If a RemoteObject is set to cache then the first time content() is called, its results will be cached locally. This is very useful for small files whose content is accessed repeatedly, but can be a cause of memory consumption for larger files.

If caching settings are changed after content is retrieved, the already retrieved content will not be affected, though any subsequent requests will use the new caching settings. That is, existing cached content will not be removed if caching is turned off.

Parameters

boolean $enabled If this is TRUE, caching will be enabled. If this is FALSE, caching will be disabled.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: $this so the method can be used in chaining.

Definition at line 525 of file RemoteObject.php.

setContentVerification ( $enabled )

Enable or disable content verification (checksum/md5).

The default behavior of a RemoteObject is to verify that the MD5 provided by the server matches the locally generated MD5 of the file contents.

If content verification is enabled, then whenever the content is fetched from the remote server, its checksum is calculated and tested against the ETag value. This provides a layer of assurance that the payload of the HTTP request was not altered during transmission.

This featured can be turned off, which is sometimes necessary on systems that do not correctly produce MD5s. Turning this off might also provide a small performance improvement on large files, but at the expense of security.

Parameters

boolean $enabled If this is TRUE, content verification is performed. The content is hashed and checked against a server-supplied MD5 hashcode. If this is FALSE, no checking is done.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: $this so the method can be used in chaining.

Definition at line 571 of file RemoteObject.php.

setHeaders ( $headers )

Set the headers.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: $this for the current object so it can be used in chaining methods.

Definition at line 281 of file RemoteObject.php.

References $name, and Container\METADATA_HEADER_PREFIX.

stream ( $refresh = FALSE )

Get the content of this object as a file stream.

This is useful for large objects. Such objects should not be read into memory all at once (as content() does), but should instead be made available as an input stream.

PHP offers low-level stream support in the form of PHP stream wrappers, and this mechanism is used internally whenever available.

If there is a local copy of the content, the stream will be read out of the content as if it were a temp-file backed in-memory resource. To ignore the local version, pass in TRUE for the $refresh parameter.

If the content is coming from a remote copy, the stream will be read directly from the underlying IO stream.

Each time stream() is called, a new stream is created. In most cases, this results in a new HTTP transaction (unless $refresh is FALSE and the content is already stored locally).

The stream is read-only.

Parameters

boolean $refresh If this is set to TRUE, any existing local modifications will be ignored and the content will be refreshed from the server. Any local changes to the object will be discarded.

Return values

resource

Returns: resource A handle to the stream, which is already opened and positioned at the beginning of the stream.

Definition at line 472 of file RemoteObject.php.

References RemoteObject\content(), RemoteObject\fetchObject(), and RemoteObject\localFileStream().

url	(	$cached = `FALSE`,
		$useSSL = `TRUE`
	)

Get the URL to this object.

If this object has been stored remotely, it will have a valid URL.

Parameters

boolean	$cached	If this value is set to TRUE, this call may return the URL to a cached (CDN) URL. Reading from a cached URL should be substantially faster than reading from a normal URL. Note, however, that a container must have CDN enabled on it before caching can be used, and a CDN must be passed into this object. See ObjectStorage::useCDN(), Container::useCDN() and RemoteObject::useCDN(). (Generally, using ObjectStorage::useCDN() is all you need to do.)
boolean	$useSSL	FOR CACHED URLS ONLY, there is an option for either SSL or non-SSL URLs. By default, we use SSL URLs because (a) it's safer, and (b) it mirrors non-CDN behavior. This can be turned off by setting $useSSL to FALSE.

Return values

string

Returns

string A URL to the object. The following considerations apply:

If the container is public, this URL can be loaded without authentication. You can, for example, pass the URL to a browser user agent.
If a CDN URL has been provided to useCDN() and $cached is TRUE...
- If the container is CDN enabled, a URL to the cache will be returned.
- Otherwise, the Swift URL will be returned.
If this object has never been saved remotely, then there will be no URL, and this will return NULL.

Definition at line 234 of file RemoteObject.php.

References ObjectStorage\$url, and ObjectStorage\cdnUrl().

useCDN	(	$url,
		$sslUrl
	)

Set the URL to this object in a CDN service.

A CDN may be used to expedite reading the object. Write operations are never performed on a CDN. Since a RemoteObject can be partially loaded, it is possible that part of the object is read from a CDN, and part from Swift. However, to accomplish this would require one to set CDN services in one place, and not in the other.

Note that if CDN was set using ObjectStorage::useCDN() or Container::useCDN(), you needn't call this method. CDN will be automatically enabled during object construction.

Setting this to NULL has the effect of turning off CDN for this object.

Parameters

string	$url	The URL to this object in CDN.
string	$sslUrl	The SSL URL to this object in CDN.

Return values

HPCloud::Storage::ObjectStorage::RemoteObject

Returns: $this for the current object so it can be used in chaining methods.

Definition at line 195 of file RemoteObject.php.

References ObjectStorage\$url, and ObjectStorage\cdnUrl().

Member Data Documentation

$allHeaders = array()

protected

All headers received from a remote are stored in this array.

Implementing subclasses can access this array for complete access to the HTTP headers.

This will be empty if the object was constructed from JSON, and may serve as a good indicator that the object does not have all attributes set.

Definition at line 68 of file RemoteObject.php.

$caching = FALSE

protected

Definition at line 57 of file RemoteObject.php.

$cdnSslUrl

protected

Definition at line 71 of file RemoteObject.php.

Referenced by RemoteObject\newFromHeaders().

$cdnUrl

protected

Definition at line 70 of file RemoteObject.php.

Referenced by RemoteObject\newFromHeaders().

$contentLength = 0

protected

Definition at line 52 of file RemoteObject.php.

$contentVerification = TRUE

protected

Definition at line 56 of file RemoteObject.php.

$etag = ''

protected

Definition at line 53 of file RemoteObject.php.

$lastModified = 0

protected

Definition at line 54 of file RemoteObject.php.

$reservedHeaders

protected

Initial value:

 array(
    'etag' => TRUE, 'content-length' => TRUE, 
    'x-auth-token' => TRUE,
    'transfer-encoding' => TRUE,
    'x-trans-id' => TRUE,
  )

Definition at line 325 of file RemoteObject.php.

The documentation for this class was generated from the following file:

src/HPCloud/Storage/ObjectStorage/RemoteObject.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

Member Data Documentation