AWS S3 Upload Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/main/java/org/example/coding_convention/file/service/S3UploadService.java
• src/main/java/org/example/coding_convention/utils/S3UrlUtils.java
• src/main/java/org/example/coding_convention/file/service/FileService.java
• src/main/java/org/example/coding_convention/file/controller/FileController.java
• src/main/java/org/example/coding_convention/file/model/FilesDto.java
• src/main/java/org/example/coding_convention/file/model/Files.java
• src/main/java/org/example/coding_convention/utils/FileUploadUtil.java
• src/main/resources/application.yml

The AWS S3 Upload Integration provides a robust mechanism for PhanesEditor to handle remote file storage and retrieval. Its primary purpose is to offload the storage of project file contents and user profile images to Amazon S3, ensuring scalability and persistent access for real-time collaborative editing features.

The integration spans several layers, including REST controllers for client interaction, specialized services for S3 operations using both Spring Cloud AWS and the AWS SDK for Java (v2), and utility classes for path generation and URL parsing. This system handles the initial registration of files, periodic content updates, and retrieval of file contents for the web-based editor.

Sources: README.md, src/main/java/org/example/coding_convention/file/service/S3UploadService.java, src/main/java/org/example/coding_convention/file/service/FileService.java

Core Components and Architecture

The S3 integration is built on a service-oriented architecture where specific components handle S3-specific logic while others manage the database state and business rules.

Service Layer Implementation

Two primary services manage S3 interactions:

• S3UploadService: Implements the UploadService interface. It uses S3Operations from Spring Cloud AWS to perform high-level upload tasks, specifically creating an InputStream from string content and uploading it to a calculated directory path.
• FileService: Manages the lifecycle of project files. It utilizes the low-level S3Client (AWS SDK v2) for granular control over operations like putObject for updates and getObject for reading contents.

Sources: src/main/java/org/example/coding_convention/file/service/S3UploadService.java:21-35, src/main/java/org/example/coding_convention/file/service/FileService.java:44-53

Integration Flow

The following diagram illustrates the flow of data during a file registration and upload process.

The diagram shows how the FileController triggers a save operation that coordinates between the S3 upload service and the local database to store file metadata.

Sources: src/main/java/org/example/coding_convention/file/controller/FileController.java:31-36, src/main/java/org/example/coding_convention/file/service/FileService.java:71-85

File Upload and Update Logic

The system distinguishes between initial file registration and periodic content updates (saving changes from the editor).

Initial Registration

When a file is first created, S3UploadService uses FileUploadUtil to generate a unique upload path based on the current date and a UUID. The content is converted to a ByteArrayInputStream with UTF-8 encoding before being sent to S3.

Sources: src/main/java/org/example/coding_convention/file/service/S3UploadService.java:29-34, src/main/java/org/example/coding_convention/utils/FileUploadUtil.java:10-21

Periodic Updates

For existing files, the FileService.updateContent method performs an in-place overwrite (putObject). It parses the existing S3 URL to extract the bucket and key before sending the new byte array.

This sequence ensures that the file content remains synchronized with the database record's timestamp.

Sources: src/main/java/org/example/coding_convention/file/service/FileService.java:44-68, src/main/java/org/example/coding_convention/utils/S3UrlUtils.java:11-47

Data Models and Configuration

S3 Configuration

Configuration is managed via application.yml, specifying the region, bucket name, and credentials.

Property	Description	Default / Example
spring.cloud.aws.credentials.access-key	AWS Access Key ID	${AWS_ACCESS_KEY}
spring.cloud.aws.credentials.secret-key	AWS Secret Access Key	${AWS_SECRET_KEY}
spring.cloud.aws.s3.bucket	Targeted S3 Bucket	${S3_BUCKET}
spring.cloud.aws.region.static	AWS Region	ap-northeast-2

Sources: src/main/resources/application.yml:45-53

Database Representation

The files table stores the link between the project and the physical S3 object.

Field	Type	Description
idx	INT	Primary Key (Auto Increment)
file_name	VARCHAR(500)	Original name of the file
file_path	VARCHAR(500)	Calculated path (without bucket)
URL	VARCHAR(500)	Full public or private URL of the S3 object
save_time_at	DATETIME	Last synchronization time with S3

Sources: src/main/java/org/example/coding_convention/file/model/Files.java:31-59, src/main/resources/data.sql:85-98

Utility and Parsing Logic

The system utilizes S3UrlUtils to handle various S3 URL formats, allowing the application to resolve bucket and key information from full strings.

URL Parsing Support

S3UrlUtils supports three main formats:

1. S3 URI: s3://bucket/key
2. Path-style URL: https://s3.region.amazonaws.com/bucket/key
3. Virtual-hosted-style URL: https://bucket.s3.region.amazonaws.com/key

Sources: src/main/java/org/example/coding_convention/utils/S3UrlUtils.java:15-47

File Path Generation

FileUploadUtil generates a base path formatted as YYYYMMDD/UUID_. This ensures that files are partitioned by date and prevents filename collisions in the S3 bucket.

Sources: src/main/java/org/example/coding_convention/utils/FileUploadUtil.java:10-21

Conclusion

The AWS S3 Upload Integration in PhanesEditor-BE provides a structured approach to remote file management. By combining high-level Spring Cloud abstractions for simple uploads and low-level SDK clients for precise updates, the system maintains a consistent state between the MariaDB metadata and S3 object storage. This architecture enables the real-time editor to persist code changes reliably across user sessions.