File Management System

Relevant source files

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

• src/main/java/org/example/coding_convention/file/controller/FileController.java
• src/main/java/org/example/coding_convention/file/service/FileService.java
• src/main/java/org/example/coding_convention/file/service/UploadService.java
• src/main/java/org/example/coding_convention/file/model/Files.java
• src/main/java/org/example/coding_convention/file/model/FilesDto.java
• src/main/java/org/example/coding_convention/file/service/S3UploadService.java
• src/main/java/org/example/coding_convention/utils/FileUploadUtil.java
• src/main/resources/data.sql

The File Management System in PhanesEditor is a core module responsible for handling the persistence, retrieval, and synchronization of source code files within collaborative projects. It facilitates a hybrid storage approach where file metadata is stored in a relational database (MariaDB), while the actual file contents are offloaded to cloud storage (Amazon S3).

This system supports essential operations such as file registration, detailed content reading, and periodic updates of file contents, which are critical for supporting real-time collaborative editing features described in the README.md:16-19.

Architecture and Data Flow

The system follows a standard layered architecture: a REST Controller for handling HTTP requests, a Service layer for business logic and cloud integration, and a Repository layer for database interactions.

Component Relationship

The following diagram illustrates how the components interact to process file-related requests.

File Storage Logic

The system distinguishes between FILE and DIRECTORY types. While directories primarily exist as metadata for structure, files involve actual data streams sent to S3.

1. Registration: When a file is registered, the contents are converted to a byte stream and uploaded to S3 via S3UploadService. The resulting S3 URL is saved in the database.
2. Updating: For periodic saves during editing, the system identifies the S3 object using the stored path/URL and performs a putObject operation to overwrite the existing content.

Sources: FileService.java:54-66, S3UploadService.java:28-34, Files.java:62-65

Data Models

Database Schema

The files table maintains the relationship between a file and its parent project, along with metadata for S3 location.

Field	Type	Description
idx	INT	Primary Key, Auto-increment
file_name	VARCHAR(80)	Name of the file with extension
file_path	VARCHAR(500)	Full path or S3 key structure
URL	VARCHAR(200)	Public/S3 URL for content access
type	VARCHAR(20)	Enum: FILE or DIRECTORY
project_idx	INT	Foreign Key to project table

Sources: data.sql:85-97, Files.java:28-58

File Types

The system uses an internal enumeration to categorize file system entries.

public enum FileType {
    DIRECTORY,
    FILE
}

Sources: Files.java:62-65

API Endpoints

The FileController exposes RESTful endpoints for managing files within projects.

Registration and Upload

Method	Endpoint	Description
POST	/file/register	Creates a new file entry and uploads initial content to S3.
POST	/file/upload	Updates the content of an existing file (used for periodic auto-saves).
GET	/file/read/{idx}	Retrieves file metadata and downloads actual content from S3.

Sources: FileController.java:32-61

File Content Retrieval Flow

When a user opens a file, the system performs a multi-step process to fetch the content.

Implementation Details

S3 Integration and Path Utilities

The system utilizes S3Operations and S3Client for cloud storage. A unique upload path is generated using a combination of the current date and a UUID to prevent collisions.

public static String makeUploadPath() {
    String basePath = "C:\\project"; // Local base for path structure
    String date = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyyMMdd"));
    // ... logic to create directory and return path string
    return date + "/" + UUID.randomUUID() + "_";
}

Sources: FileUploadUtil.java:10-21, S3UploadService.java:31-33

Content Updates

The update mechanism is optimized for high-frequency saves during editing sessions. It uses S3UrlUtils to parse existing URLs into bucket and key components for targeted S3 overwrites.

@Transactional
public void updateContent(FilesDto.ContentUpdateReq req) {
    Files entity = fileRepository.findByPath(req.getFileName()).orElseThrow(...);
    var parts = S3UrlUtils.parse(entity.getURL());
    byte[] bytes = req.getFileContents().getBytes(StandardCharsets.UTF_8);

    PutObjectRequest por = PutObjectRequest.builder()
            .bucket(parts.bucket())
            .key(parts.key())
            .contentType("text/plain; charset=utf-8")
            .build();

    s3Client.putObject(por, RequestBody.fromBytes(bytes));
    entity.setSaveTimeAt(LocalDateTime.now());
}

Sources: FileService.java:41-61

Summary

The File Management System provides a robust backbone for the PhanesEditor by abstracting file storage logic away from the main editing features. By combining JPA-managed metadata with Amazon S3 for content storage, it ensures scalability and performance. The system's ability to handle both standard HTTP URLs and S3 URIs within readContentByIdx makes it versatile for different deployment environments and storage configurations.