{"id":23067943,"url":"https://github.com/migangqui/cloud-storage-spring-api","last_synced_at":"2025-08-15T11:34:13.051Z","repository":{"id":42046826,"uuid":"225855501","full_name":"migangqui/cloud-storage-spring-api","owner":"migangqui","description":"Manage files from AWS S3, Google Cloud Storag, Azure Blob Storage and Dropbox in Spring","archived":false,"fork":false,"pushed_at":"2023-11-28T20:59:43.000Z","size":210,"stargazers_count":20,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-15T02:54:45.720Z","etag":null,"topics":["amazon","aws","aws-s3","azure","azure-storage-blob","cloud-storage","dropbox","google-cloud","google-cloud-storage","java","kotlin","s3","s3-bucket","spring"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/migangqui.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-04T11:53:03.000Z","updated_at":"2024-06-21T13:06:16.000Z","dependencies_parsed_at":"2023-02-16T10:15:41.170Z","dependency_job_id":null,"html_url":"https://github.com/migangqui/cloud-storage-spring-api","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migangqui%2Fcloud-storage-spring-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migangqui%2Fcloud-storage-spring-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migangqui%2Fcloud-storage-spring-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migangqui%2Fcloud-storage-spring-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/migangqui","download_url":"https://codeload.github.com/migangqui/cloud-storage-spring-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229911213,"owners_count":18143275,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon","aws","aws-s3","azure","azure-storage-blob","cloud-storage","dropbox","google-cloud","google-cloud-storage","java","kotlin","s3","s3-bucket","spring"],"created_at":"2024-12-16T05:19:33.318Z","updated_at":"2024-12-16T05:19:33.905Z","avatar_url":"https://github.com/migangqui.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cloud Storage Spring (Java/Kotlin)\n\n![GitHub last commit](https://img.shields.io/github/last-commit/migangqui/cloud-storage-spring-api?style=for-the-badge)\n![Maven Central](https://img.shields.io/maven-central/v/com.github.sevtech-dev/cloud-storage-spring-java?style=for-the-badge)\n\nHere we are a Java and a Kotlin API to manage files of AWS S3, Google Cloud Storage, Azure Blob Storage and Dropbox in Spring framework.\n\n\u003ch4\u003eAWS S3\u003c/h4\u003e\n\u003cimg src=\"https://assets.zabbix.com/img/brands/aws_s3.svg\" width=\"13%\"\u003e\n\u003ch4\u003eGoogle Cloud Storage\u003c/h4\u003e\n\u003cimg src=\"https://cdn.www.denodo.com/cdn/farfuture/azTr0Jzv8x3dQ7S_N1-JaX0ywwrAFrw5JS9Vx7VtBHA/mtime:1614168093/sites/default/files/public/images/icon-google-cloud-storage-logo.png\" width=\"10%\"\u003e\n\u003ch4\u003eAzure Store Blob\u003c/h4\u003e\n\u003cimg src=\"https://dellenny.com/wp-content/uploads/2019/04/azure-storage-blob.png\" width=\"13%\"\u003e\n\u003ch4\u003eDropbox\u003c/h4\u003e\n\u003cimg src=\"https://cfl.dropboxstatic.com/static/images/logo_catalog/twitter-card-glyph_m1%402x.png\" width=\"10%\"\u003e\n\nIn order to use it, are necessaries the following steps:\n\n### Add dependency to Maven or Gradle:\n\nIf you use Java:\n\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003ecom.github.sevtech-dev\u003c/groupId\u003e\n\t\u003cartifactId\u003ecloud-storage-spring-java\u003c/artifactId\u003e\n\t\u003cversion\u003e${currentVersion}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n```groovy\nimplementation 'com.github.sevtech-dev:cloud-storage-spring-java:${currentVersion}'\n```\n\nIf you use Kotlin:\n\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003ecom.github.sevtech-dev\u003c/groupId\u003e\n\t\u003cartifactId\u003ecloud-storage-spring-kotlin\u003c/artifactId\u003e\n\t\u003cversion\u003e${currentVersion}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n```groovy\nimplementation 'com.github.sevtech-dev:cloud-storage-spring-kotlin:${currentVersion}'\n```\n\n```${currentVersion}``` right now is ```1.1.2```\n\n## Configuration\n\nTo enable the wanted client configuration, you must set the following properties:\n\nTo AWS S3:\n```yaml\naws:\n  s3:\n    enabled: true\n    accessKey: [AMAZON_ACCESS_KEY]\n    secretKey: [AMAZON_SECRET_KEY]\n    bucket:\n      name: yourbucketname\n    region: [GovCloud(\"us-gov-west-1\"),\n             US_EAST_1(\"us-east-1\"),\n             US_WEST_1(\"us-west-1\"),\n             US_WEST_2(\"us-west-2\"),\n             EU_WEST_1(\"eu-west-1\"),\n             EU_CENTRAL_1(\"eu-central-1\"),\n             AP_SOUTH_1(\"ap-south-1\"),\n             AP_SOUTHEAST_1(\"ap-southeast-1\"),\n             AP_SOUTHEAST_2(\"ap-southeast-2\"),\n             AP_NORTHEAST_1(\"ap-northeast-1\"),\n             AP_NORTHEAST_2(\"ap-northeast-2\"),\n             SA_EAST_1(\"sa-east-1\"),\n             CN_NORTH_1(\"cn-north-1\")]*\n```\n** Only one and only the string of the region.\n\n* **accessKey/secretKey**: the keys to connect to AWS. To get it, check out \u003ca href=\"https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html\" target=\"_blank\"\u003ethis information\u003c/a\u003e.\n* **bucket.name**: the bucket name.\n* **region**: AWS region where your bucket is located.\n\nTo Google Cloud Storage:\n```yaml\ngcp:\n  storage:\n    enabled: true\n    bucket:\n      name: yourbucketname\n    keyfile: \"where-you-keyfile\"\n```\n* **bucket.name**: the bucket name.\n* **keyfile**: the file to authenticate. To generate it, check out \u003ca href=\"https://cloud.google.com/iam/docs/creating-managing-service-account-keys#iam-service-account-keys-create-gcloud\" target=\"_blank\"\u003ethis information\u003c/a\u003e.\n\nTo Azure Blob Storage:\n```yaml\nazure:\n  blob:\n    storage:\n      enabled: true\n      connectionString: \"your-connection-string\"\n      container:\n        name: containername\n```\n* **connectionString**: to get it, check out \u003ca href=\"https://docs.microsoft.com/es-es/azure/storage/common/storage-account-keys-manage?tabs=azure-portal\" target=\"_blank\"\u003ethis information\u003c/a\u003e.\n* **container.name**: name of your files container.\n\nTo Dropbox:\n```yaml\ndropbox:\n  enabled: true\n  accessToken: \"accessToken\"\n  clientIdentifier: \"clientIdentifier\"\n```\n* **accessToken**: to get it, check out \u003ca href=\"http://99rabbits.com/get-dropbox-access-token/\" target=\"_blank\"\u003ethis information\u003c/a\u003e.\n* **clientIdentifier**: name of your app.\n\n## Enable async\n\nAdd ```@EnableAsync``` annotation in your Spring Application class to enable async upload method.\n\n## File size\n\nTo controle max size of files you can upload, set the following properties:\n```yaml\nspring:\n  servlet:\n    multipart:\n      max-file-size: 128KB\n      max-request-size: 128KB\n```\n\n## How to use\n\nYou have to inject ```StorageService``` as dependency in your Spring component. \n\nIf you use more than one provider, you must name your bean\nas \u003cb\u003eawsS3Service\u003c/b\u003e to AWS S3, \u003cb\u003egoogleCloudStorageService\u003c/b\u003e to Google Cloud Storage, \u003cb\u003eazureBlobStorageService\u003c/b\u003e to Azure Blob Storage,\nand \u003cb\u003edropboxService\u003c/b\u003e to Dropbox.\n\nThe service provide these methods:\n\n##### Java\n```java\npublic interface StorageService {\n\t\n    UploadFileResponse uploadFile(UploadFileRequest request);\n    \n    Future\u003cUploadFileResponse\u003e uploadFileAsync(UploadFileRequest request);\n\n    GetFileResponse getFile(GetFileRequest request);\n\n    DeleteFileResponse deleteFile(DeleteFileRequest request);\n\n}\n```\n##### Kotlin\n```kotlin\ninterface StorageService {\n    \n    fun uploadFile(request: UploadFileRequest): UploadFileResponse\n    \n    fun uploadFileAsync(request: UploadFileRequest): Future\u003cUploadFileResponse\u003e\n\n    fun getFile(request: GetFileRequest): GetFileResponse\n\n    fun deleteFile(request: DeleteFileRequest): DeleteFileResponse\n\n}\n```\n\n### Model\n\n#### Upload\n\n*UploadFileRequest*\n\n* **stream (InputStream)**: content of your file.\n* **folder (String)**: folder where you want to save the file. Ex: folder/subfolder1/subfolder2\n* **name (String)**: name of the uploaded file. Ex: image.jpg, image\n* **contentType (String)**: type of content of the file.\n* **bucketName (String, optional)**\n* **accessControl**\n\n*UploadFileResponse*\n\n* **fileName (String)**: final name of the uploaded file.\n* **status (int)**: status of the operation. 200 OK or 500 KO.\n* **cause (String)**: cause of the fail.\n* **exception (Exception)**: exception.\n* **comment (String)**: optional comment.\n\n#### Get\n\n*GetFileRequest*\n\n* **path (String)**: complete path where you want to get the file from. Ex: folder/subfolder1/subfolder2/file.jpg\n* **bucketName (String, optional)**\n\n*GetFileResponse*\n\n* **stream (InputStream)**: content of your file.\n* **status (int)**: status of the operation. 200 OK or 500 KO.\n* **cause (String)**: cause of the fail.\n* **exception (Exception)**: exception.\n\n#### Delete\n\n*DeleteFileRequest*\n\n* **path (String)**: complete path where you want to get the file from. Ex: folder/subfolder1/subfolder2/file.jpg\n* **bucketName (String, optional)**\n\n*DeleteFileResponse*\n\n* **result boolean)**: result of the deletion. true ok or false ko.\n* **status (int)**: status of the operation. 200 OK or 500 KO.\n* **cause (String)**: cause of the fail.\n* **exception (Exception)**: exception.\n\n## Test in local\n\n### AWS S3: Localstack support\n\nThis library can be tested with \u003ca href=\"https://github.com/localstack/localstack\"\u003eLocalstack\u003c/a\u003e. You only have to set the following properties in your application.yml:\n\n```yaml\naws:\n  s3:\n    localstack:\n      enabled: true\n      endpoint: http://localhost:4572\n      region: us-east-1\n```\n\nIn order to run easily Localstack, I have added ```docker-compose.yml``` file to the folder ```localstack```. \nYou have run the command ```docker-compose up``` to make it work.\n\nI hardly recommend install AWS CLI in your local. It helps you to manage the buckets to run the tests with Localstack.\nHere you are the documentation to install the version 2: \u003chttps://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html\u003e\n\nTo create a local bucket you must run this command `aws2 --endpoint-url=http://localhost:4572 s3 mb s3://mytestbucket`\n\nTo check out if the bucket has been created run this command `aws2 --endpoint-url=http://localhost:4572 s3 ls`\n\nWhen you create a bucket, you have to add `yourbucketname.localhost` to your hosts local file mapped to `127.0.0.1`.\n\nHere we are the AWS CLI S3 command options: \u003chttps://docs.aws.amazon.com/en_en/cli/latest/userguide/cli-services-s3-commands.html\u003e\n\n## Next adds\n* Support to \u003ca href=\"https://www.alibabacloud.com/product/oss?spm=a3c0i.7911826.1389108.dnavproductstorage1.441914b3M6269v\" target=\"_blank\"\u003eAlibaba Cloud Object Storage Service\u003c/a\u003e, \u003ca href=\"https://www.oracle.com/es/cloud/storage/object-storage/\" target=\"_blank\"\u003eOracle Object Storage\u003c/a\u003e, Google Drive...\n* File permissions management.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE.md file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmigangqui%2Fcloud-storage-spring-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmigangqui%2Fcloud-storage-spring-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmigangqui%2Fcloud-storage-spring-api/lists"}