https://github.com/kaliber-scala/play-s3
S3 module for Play
https://github.com/kaliber-scala/play-s3
Last synced: about 1 year ago
JSON representation
S3 module for Play
- Host: GitHub
- URL: https://github.com/kaliber-scala/play-s3
- Owner: kaliber-scala
- License: mit
- Archived: true
- Created: 2013-02-28T13:49:30.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2019-04-11T19:40:33.000Z (over 7 years ago)
- Last Synced: 2024-08-03T18:19:52.494Z (almost 2 years ago)
- Language: Scala
- Homepage:
- Size: 266 KB
- Stars: 119
- Watchers: 32
- Forks: 49
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-playframework - play-s3 - Amazon Simple Storage Service (S3) module for Play 2.6 (Libraries / Others)
README
*This repository is no longer maintained*
Just create a fork, if you want I can list it here.
-------------
Amazon Simple Storage Service (S3) module for Play 2.6
=====================================================
A minimal S3 API wrapper. Allows you to list, get, add and remove items from a bucket.
Has some extra features that help with direct upload and authenticated url generation.
**Note: this version uses the new aws 4 signer, this requires you to correctly set the region**
Important changes
-----------------
**10.0.0**
- Upgraded to Play 2.7
-----------------
**9.0.0**
- Upgraded to Play 2.6
- Upgraded to Scala 2.12
**8.0.0**
- Upgraded to Play 2.5
**7.0.0**
- Organisation has been changed to 'net.kaliber'
- Resolver (maven repository) has been moved
- `fromConfig` and `fromConfiguration` methods have been renamed to `fromApplication`. Added `fromConfiguration`
methods that can be used without access to an application (useful for application loaders introduced in Play 2.4)
Installation
------------
``` scala
val appDependencies = Seq(
"net.kaliber" %% "play-s3" % "9.0.0"
// use the following version for play 2.5
"net.kaliber" %% "play-s3" % "8.0.0"
// use the following version for play 2.4
"net.kaliber" %% "play-s3" % "7.0.2"
// use the following version for play 2.3
"nl.rhinofly" %% "play-s3" % "6.0.0"
// use the following version for play 2.2
//"nl.rhinofly" %% "play-s3" % "4.0.0"
// use the following version for play 2.1
//"nl.rhinofly" %% "play-s3" % "3.1.1"
)
// use the following for play 2.5 and 2.4
resolvers += "Kaliber Internal Repository" at "https://jars.kaliber.io/artifactory/libs-release-local"
// use the following for play 2.3 and below
resolvers += "Rhinofly Internal Repository" at "http://maven-repository.rhinofly.net:8081/artifactory/libs-release-local"
```
Configuration
-------------
`application.conf` should contain the following information:
``` scala
aws.accessKeyId=AmazonAccessKeyId
aws.secretKey=AmazonSecretKey
```
If you are hosting in a specific region that can be specified. If you are using another S3
implementation (like riakCS), you can customize the domain name and https usage with these values:
``` scala
#default is us-east-1
s3.region="eu-west-1"
#default is determined by the region, see: http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region
s3.host="your.domain.name"
#default is true
s3.https=false
#default is true
#required in case dots are present in the bucket name and https is enabled
s3.pathStyleAccess=false
```
Usage
-----
Getting a S3 instance:
``` scala
val s3 = S3.fromApplication(playApplication)
// or
val s3 = S3.fromConfiguration(wsClient, playConfiguration)
```
Getting a bucket:
``` scala
val bucket = s3.getBucket("bucketName")
```
Adding a file:
``` scala
//not that acl and headers are optional, the default value for acl is set to PUBLIC_READ.
val result = bucket + BucketFile(fileName, mimeType, byteArray, acl, headers)
//or
val result = bucket add BucketFile(fileName, mimeType, byteArray, acl, headers)
result
.map { unit =>
Logger.info("Saved the file")
}
.recover {
case S3Exception(status, code, message, originalXml) => Logger.info("Error: " + message)
}
```
Removing a file:
``` scala
val result = bucket - fileName
//or
val result = bucket remove fileName
```
Retrieving a file:
``` scala
val result = bucket get "fileName"
result.map {
case BucketFile(name, contentType, content, acl, headers) => //...
}
//or
val file = Await.result(result, 10 seconds)
val BucketFile(name, contentType, content, acl, headers) = file
```
Listing the contents of a bucket:
``` scala
val result = bucket.list
result.map { items =>
items.map {
case BucketItem(name, isVirtual) => //...
}
}
//or using a prefix
val result = bucket list "prefix"
```
Retrieving a private url:
``` scala
val url = bucket.url("fileName", expirationFromNowInSeconds)
```
Renaming a file:
``` scala
val result = bucket rename("oldFileName", "newFileName", ACL)
```
Multipart file upload:
``` scala
// Retrieve an upload ticket
val result:Future[BucketFileUploadTicket] =
bucket initiateMultipartUpload BucketFile(fileName, mimeType)
// Upload the parts and save the tickets
val result:Future[BucketFilePartUploadTicket] =
bucket uploadPart (uploadTicket, BucketFilePart(partNumber, content))
// Complete the upload using both the upload ticket and the part upload tickets
val result:Future[Unit] =
bucket completeMultipartUpload (uploadTicket, partUploadTickets)
```
Updating the ACL of a file:
``` scala
val result:Future[Unit] = bucket updateACL ("fileName", ACL)
```
Retrieving the ACL of a file:
``` scala
val result = testBucket.getAcl("private2README.txt")
for {
aclList <- result
grant <- aclList
} yield
grant match {
case Grant(FULL_CONTROL, CanonicalUser(id, displayName)) => //...
case Grant(READ, Group(uri)) => //...
}
```
Browser upload helpers:
``` scala
val `1 minute from now` = System.currentTimeMillis + (1 * 60 * 1000)
// import condition builders
import fly.play.s3.upload.Condition._
// create a policy and set the conditions
val policy =
testBucket.uploadPolicy(expiration = new Date(`1 minute from now`))
.withConditions(
key startsWith "test/",
acl eq PUBLIC_READ,
successActionRedirect eq expectedRedirectUrl,
header(CONTENT_TYPE) startsWith "text/",
meta("tag").any)
.toPolicy
// import Form helper
import fly.play.s3.upload.Form
val formFieldsFromPolicy = Form(policy).fields
// convert the form fields from the policy to an actial form
formFieldsFromPolicy
.map {
case FormElement(name, value, true) =>
s""""""
case FormElement(name, value, false) =>
s""""""
}
// make sure you add the file form field as last
val allFormFields =
formFieldsFromPolicy.mkString("\n") +
""""""
```
More examples can be found in the `S3Spec` in the `test` folder. In order to run the tests you need
an `application.conf` file in the `test/conf` that looks like this:
``` scala
aws.accessKeyId="..."
aws.secretKey="..."
s3.region="eu-west-1"
testBucketName=s3playlibrary.rhinofly.net
```