s3sdk

Class AmazonS3

lucee.Component
    extended by s3sdk.AmazonS3

Copyright 2005-2007 ColdBox Framework by Luis Majano and Ortus Solutions, Corp www.coldboxframework.com | www.luismajano.com | www.ortussolutions.com Amazon S3 REST Wrapper Written by Joe Danziger (joe@ajaxcf.com) with much help from dorioo on the Amazon S3 Forums. See the readme for more details on usage and methods. Thanks to Steve Hicks for the bucket ACL updates. Thanks to Carlos Gallupa for the EU storage location updates. Thanks to Joel Greutman for the fix on the getObject link. Thanks to Jerad Sloan for the Cache Control headers. Version 1.7 - Released: December 15, 2008 Version 2.0 - Luis Majano updated for ColdBox and extra features. You will have to create some settings in your ColdBox configuration file: s3_accessKey : The Amazon access key s3_secretKey : The Amazon secret key s3_encryption_charset : encryptyion charset (Optional, defaults to utf-8) s3_ssl : Whether to use ssl on all cals or not (Optional, defaults to false)

Class Attributes:
  • singleton
  •  
  • synchronized : false
  •  
  • accessors : true
  •  
  • persistent : false
  •  
    Property Summary
    type property default serializable required
    any accessKey


    • access = public
    • returntype = any
    true false
    any encryption_charset


    • access = public
    • returntype = any
    true false
    any log


    • access = public
    • returntype = any
    • inject = logbox:logger:{this}
    true false
    any secretKey


    • access = public
    • returntype = any
    true false
    any ssl


    • access = public
    • returntype = any
    true false
    any URLEndpoint


    • access = public
    • returntype = any
    true false
    Constructor Summary
    init(string accessKey, string secretKey, [string encryption_charset='UTF-8'], [boolean ssl='false'], [string awsRegion='us-east-1'])
          Create a new S3SDK Instance.
    Method Summary
    boolean copyObject(string fromBucket, string fromURI, string toBucket, string toURI, [string acl='[runtime expression]'], [struct metaHeaders='[runtime expression]'])
         Copies an object.
    struct createMetaHeaders([struct metaHeaders='[runtime expression]'])
         Create a structure of Amazon-enabled metadata headers.
    string createSignature(string stringToSign)
         Create a v2 signature to sign the request.
    boolean deleteBucket(string bucketName, [boolean force='false'])
         Deletes a bucket.
    boolean deleteObject(string bucketName, string uri)
         Deletes an object.
    array getAccessControlPolicy(string bucketName, [string uri=''])
         Gets a bucket's or object's ACL policy.
    string getAccessKey()
    string getAuthenticatedURL(string bucketName, string uri, [string minutesValid='60'], [boolean virtualHostStyle='false'], [boolean useSSL='false'])
         Returns a query string authenticated URL to an object in S3.
    array getBucket(string bucketName, [string prefix=''], [string marker=''], [string maxKeys=''], [string delimiter=''])
         Lists information about the objects of a bucket.
    string getBucketLocation(string bucketName)
         Get the S3 region for the bucket provided.
    string getBucketVersionStatus(string bucketName)
         Get the versioning status of a bucket.
    string getEncryption_charset()
    string getLog()
    struct getObjectInfo(string bucketName, string uri)
         Get an object's metadata information.
    string getSecretKey()
    string getSsl()
    string getURLEndpoint()
    boolean hasBucket(string bucketName)
         Checks for the existance of a bucket.
    private binary HMAC_SHA1(string signKey, string signMessage)
         NSA SHA-1 Algorithm: RFC 2104HMAC-SHA1.
    array listBuckets()
         List all the buckets associated with the Amazon credentials.
    boolean putBucket(string bucketName, [string acl='[runtime expression]'], [string location='USA'])
         Create a new bucket.
    string putObject(string bucketName, [string uri=''], [any data=''], [string contentDisposition=''], [string contentType='text/plain'], [numeric HTTPTimeout='300'], [string cacheControl='no-store, no-cache, must-revalidate'], [string expires=''], [string acl='[runtime expression]'], [struct metaHeaders='[runtime expression]'])
         Puts an object into a bucket.
    string putObjectFile(string bucketName, string filepath, [string uri=''], [string contentType='binary/octet-stream'], [numeric HTTPTimeout='300'], [string cacheControl='no-store, no-cache, must-revalidate'], [string expires=''], [string acl='[runtime expression]'], [struct metaHeaders='[runtime expression]'])
         Puts an object from a local file in to a bucket.
    string putObjectFolder(string bucketName, [string uri=''], [string contentType='binary/octet-stream'], [numeric HTTPTimeout='300'], [string cacheControl='no-store, no-cache, must-revalidate'], [string expires=''], [string acl='[runtime expression]'], [struct metaHeaders='[runtime expression]'])
         Puts an folder in to a bucket.
    boolean renameObject(string oldBucketName, string oldFileKey, string newBucketName, string newFileKey)
         Renames an object by copying then deleting original.
    private struct S3Request([string method='GET'], [string resource=''], [any body=''], [struct headers='[runtime expression]'], [struct amzHeaders='[runtime expression]'], [struct parameters='[runtime expression]'], [numeric timeout='20'])
         Make a request to Amazon S3.
    any setAccessKey(any accessKey)
    AmazonS3 setAuth(string accessKey, string secretKey)
         Set the Amazon Credentials.
    boolean setBucketVersionStatus(string bucketName, [boolean version='true'])
         Set versioning status for a bucket.
    any setEncryption_charset(any encryption_charset)
    any setLog(any log)
    any setSecretKey(any secretKey)
    AmazonS3 setSSL([boolean useSSL='true'])
         Set the ssl flag.
    any setURLEndpoint(any URLEndpoint)
     
    Methods inherited from class lucee.Component
    None

    Constructor Detail

    init

    public init(string accessKey, string secretKey, [string encryption_charset='UTF-8'], [boolean ssl='false'], [string awsRegion='us-east-1'])

    Create a new S3SDK Instance

    Parameters:
    accessKey - The Amazon access key.
    secretKey - The Amazon secret key.
    encryption_charset
    ssl - True if the request should use SSL. Defaults to false.
    awsRegion

    Property Detail

    accessKey

    property any accessKey

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    encryption_charset

    property any encryption_charset

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    log

    property any log

    Attributes:
    access - public
    required - false
    returntype - any
    inject - logbox:logger:{this}
    serializable - true

    secretKey

    property any secretKey

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    ssl

    property any ssl

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    URLEndpoint

    property any URLEndpoint

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    Method Detail

    copyObject

    public boolean copyObject(string fromBucket, string fromURI, string toBucket, string toURI, [string acl='[runtime expression]'], [struct metaHeaders='[runtime expression]'])

    Copies an object.

    Parameters:
    fromBucket - The source bucket
    fromURI - The source URI
    toBucket - The destination bucket
    toURI - The destination URI
    acl - The Amazon security access policy to use. Defaults to private.
    metaHeaders - Additonal metadata headers to add.
    Returns:
    True if the object was copied correctly.

    createMetaHeaders

    public struct createMetaHeaders([struct metaHeaders='[runtime expression]'])

    Create a structure of Amazon-enabled metadata headers.

    Parameters:
    metaHeaders - Headers to convert to the Amazon meta headers.
    Returns:
    A struct of Amazon-enabled metadata headers.

    createSignature Deprecated

    public string createSignature(string stringToSign)

    Create a v2 signature to sign the request.

    Deprecated:
    true
    Parameters:
    stringToSign - The string to sign for the request.
    Returns:
    A signed string to send with the request.

    deleteBucket

    public boolean deleteBucket(string bucketName, [boolean force='false'])

    Deletes a bucket.

    Parameters:
    bucketName - The name of the bucket to delete.
    force - If true, delete the contents of the bucket before deleting the bucket.
    Returns:
    True, if the bucket was deleted successfully.

    deleteObject

    public boolean deleteObject(string bucketName, string uri)

    Deletes an object.

    Parameters:
    bucketName - The bucket name the object resides in.
    uri - The file object uri to delete.
    Returns:
    Returns true if the object is deleted successfully.

    getAccessControlPolicy

    public array getAccessControlPolicy(string bucketName, [string uri=''])

    Gets a bucket's or object's ACL policy.

    Parameters:
    bucketName - The bucket to get the ACL.
    uri - An optional resource uri to get the ACL.
    Returns:
    An array containing the ACL for the given resource.

    getAccessKey

    public string getAccessKey()


    getAuthenticatedURL

    public string getAuthenticatedURL(string bucketName, string uri, [string minutesValid='60'], [boolean virtualHostStyle='false'], [boolean useSSL='false'])

    Returns a query string authenticated URL to an object in S3. Defaults to true.

    Parameters:
    bucketName - The bucket the object resides in.
    uri - The uri to the object to create a link for.
    minutesValid - The minutes the link is valid for. Defaults to 60 minutes.
    virtualHostStyle - Whether to use virtual bucket style or path style.
    useSSL - Use SSL for the returned url.
    Returns:
    An authenticated url to the resource.

    getBucket

    public array getBucket(string bucketName, [string prefix=''], [string marker=''], [string maxKeys=''], [string delimiter=''])

    Lists information about the objects of a bucket.

    Parameters:
    bucketName - The bucket name to list.
    prefix - Limits the response to keys which begin with the indicated prefix, if any.
    marker - Indicates where in the bucket to begin listing, if any.
    maxKeys - The maximum number of keys you'd like to see in the response body, if any.
    delimiter - The delimiter to use in the keys, if any.
    Returns:
    The bucket contents.

    getBucketLocation

    public string getBucketLocation(string bucketName)

    Get the S3 region for the bucket provided.

    Parameters:
    bucketName - The bucket for which to fetch the region.
    Returns:
    The region code for the bucket.

    getBucketVersionStatus

    public string getBucketVersionStatus(string bucketName)

    Get the versioning status of a bucket.

    Parameters:
    bucketName - The bucket for which to fetch the versioning status.
    Returns:
    The bucket version status or an empty string if there is none.

    getEncryption_charset

    public string getEncryption_charset()


    getLog

    public string getLog()


    getObjectInfo

    public struct getObjectInfo(string bucketName, string uri)

    Get an object's metadata information.

    Parameters:
    bucketName - The bucket the object resides in.
    uri - The object URI to retrieve the info.
    Returns:
    The object's metadata information.

    getSecretKey

    public string getSecretKey()


    getSsl

    public string getSsl()


    getURLEndpoint

    public string getURLEndpoint()


    hasBucket

    public boolean hasBucket(string bucketName)

    Checks for the existance of a bucket

    Parameters:
    bucketName - The bucket to check for its existance.
    Returns:
    True if the bucket exists.

    HMAC_SHA1

    private binary HMAC_SHA1(string signKey, string signMessage)

    NSA SHA-1 Algorithm: RFC 2104HMAC-SHA1

    Parameters:
    signKey
    signMessage

    listBuckets

    public array listBuckets()

    List all the buckets associated with the Amazon credentials.

    Returns:
    true

    putBucket

    public boolean putBucket(string bucketName, [string acl='[runtime expression]'], [string location='USA'])

    Create a new bucket.

    Parameters:
    bucketName - The name for the new bucket.
    acl - The ACL policy for the new bucket.
    location - The bucket location.
    Returns:
    True if the bucket was created successfully.

    putObject

    public string putObject(string bucketName, [string uri=''], [any data=''], [string contentDisposition=''], [string contentType='text/plain'], [numeric HTTPTimeout='300'], [string cacheControl='no-store, no-cache, must-revalidate'], [string expires=''], [string acl='[runtime expression]'], [struct metaHeaders='[runtime expression]'])

    Puts an object into a bucket. This can be binary, string, or anything you'd like. Example: public,max-age=864000 ( 10 days ). For more info look here: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.9 Defaults to public-read.

    Parameters:
    bucketName - The bucket in which to store the object.
    uri - The destination uri key to use when saving the object.
    data - The content to save as data.
    contentDisposition - The content-disposition header to use when downloading the file.
    contentType - The file/data content type. Defaults to text/plain.
    HTTPTimeout - The HTTP timeout to use.
    cacheControl - The caching header to send. Defaults to no caching.
    expires - Sets the expiration header of the object in days.
    acl - The Amazon security access policy to use.
    metaHeaders - Additonal metadata headers to add.
    Returns:
    The object's eTag.

    putObjectFile

    public string putObjectFile(string bucketName, string filepath, [string uri=''], [string contentType='binary/octet-stream'], [numeric HTTPTimeout='300'], [string cacheControl='no-store, no-cache, must-revalidate'], [string expires=''], [string acl='[runtime expression]'], [struct metaHeaders='[runtime expression]'])

    Puts an object from a local file in to a bucket. If not provided, the name of the file will be used. Example: public,max-age=864000 ( 10 days ). For more info look here: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.9 Defaults to public-read.

    Parameters:
    bucketName - The bucket in which to store the object.
    filepath - The absolute file path to read in the binary.
    uri - The destination uri key to use when saving the object.
    contentType - The file content type. Defaults to binary/octet-stream.
    HTTPTimeout - The HTTP timeout to use
    cacheControl - The caching header to send. Defaults to no caching.
    expires - Sets the expiration header of the object in days.
    acl - The Amazon security access policy to use.
    metaHeaders - Additonal metadata headers to add.
    Returns:
    The file's eTag

    putObjectFolder

    public string putObjectFolder(string bucketName, [string uri=''], [string contentType='binary/octet-stream'], [numeric HTTPTimeout='300'], [string cacheControl='no-store, no-cache, must-revalidate'], [string expires=''], [string acl='[runtime expression]'], [struct metaHeaders='[runtime expression]'])

    Puts an folder in to a bucket. If not provided, the name of the folder will be used. Example: public,max-age=864000 ( 10 days ). For more info look here: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.9 Defaults to public-read.

    Parameters:
    bucketName - The bucket in which to store the object.
    uri - The destination uri key to use when saving the object.
    contentType - The folder content type. Defaults to binary/octet-stream.
    HTTPTimeout - The HTTP timeout to use
    cacheControl - The caching header to send. Defaults to no caching.
    expires - Sets the expiration header of the object in days.
    acl - The Amazon security access policy to use.
    metaHeaders - Additonal metadata headers to add.
    Returns:
    The folder's eTag

    renameObject

    public boolean renameObject(string oldBucketName, string oldFileKey, string newBucketName, string newFileKey)

    Renames an object by copying then deleting original.

    Parameters:
    oldBucketName - The source bucket.
    oldFileKey - The source URI.
    newBucketName - The destination bucket.
    newFileKey - The destination URI.
    Returns:
    True if the rename operation is successful.

    S3Request

    private struct S3Request([string method='GET'], [string resource=''], [any body=''], [struct headers='[runtime expression]'], [struct amzHeaders='[runtime expression]'], [struct parameters='[runtime expression]'], [numeric timeout='20'])

    Make a request to Amazon S3.

    Parameters:
    method - The HTTP method for the request.
    resource - The resource to hit in the Amazon S3 service.
    body - The body content of the request, if passed.
    headers - A struct of HTTP headers to send.
    amzHeaders - A struct of special Amazon headers to send.
    parameters - A struct of HTTP URL parameters to send.
    timeout - The default CFHTTP timeout.
    Returns:
    The response information.

    setAccessKey

    public any setAccessKey(any accessKey)

    Parameters:
    accessKey

    setAuth

    public AmazonS3 setAuth(string accessKey, string secretKey)

    Set the Amazon Credentials.

    Parameters:
    accessKey - The Amazon access key.
    secretKey - The Amazon secret key.
    Returns:
    The AmazonS3 Instance.

    setBucketVersionStatus

    public boolean setBucketVersionStatus(string bucketName, [boolean version='true'])

    Set versioning status for a bucket.

    Parameters:
    bucketName - The bucket to set the versioning status.
    version - The status for the versioning property.
    Returns:
    True if the request was successful.

    setEncryption_charset

    public any setEncryption_charset(any encryption_charset)

    Parameters:
    encryption_charset

    setLog

    public any setLog(any log)

    Parameters:
    log

    setSecretKey

    public any setSecretKey(any secretKey)

    Parameters:
    secretKey

    setSSL

    public AmazonS3 setSSL([boolean useSSL='true'])

    Set the ssl flag. Alters the internal URL endpoint accordingly.

    Parameters:
    useSSL - True if SSL should be used for the requests.
    Returns:
    The AmazonS3 instance.

    setURLEndpoint

    public any setURLEndpoint(any URLEndpoint)

    Parameters:
    URLEndpoint