Utility Classes & Helpers
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/org/example/coding_convention/utils/FileUploadUtil.java
- src/main/java/org/example/coding_convention/utils/S3UrlUtils.java
- src/main/java/org/example/coding_convention/file/service/S3UploadService.java
- src/main/java/org/example/coding_convention/file/service/FileService.java
- src/main/java/org/example/coding_convention/config/SwaggerConfig.java
Introduction
Utility classes and helper modules in the PhanesEditor-BE project provide essential cross-cutting functionalities that support file management, cloud storage interactions, and API documentation. These components are designed to be stateless and reusable, ensuring consistency across the application's service layer, particularly regarding how files are named, paths are generated, and external resource identifiers (like S3 URLs) are parsed.
The primary focus of these utilities is to bridge the gap between the application's internal file logic and external cloud storage providers like Amazon S3. They handle tasks ranging from generating unique directory structures based on timestamps to extracting bucket and key information from complex URL strings.
Sources: src/main/java/org/example/coding_convention/utils/FileUploadUtil.java, src/main/java/org/example/coding_convention/utils/S3UrlUtils.java
File and Path Management
FileUploadUtil
The FileUploadUtil class is responsible for generating standardized upload paths for files within the system. It uses a date-based directory structure combined with unique identifiers to prevent filename collisions.
- Path Generation: It creates a base path (defaulting to
C:\project) and appends the current date inyyyyMMddformat. - Uniqueness: It appends a
UUID.randomUUID()to the path to ensure that even files uploaded on the same day remain distinct.
The diagram shows the logic for generating a unique file path string including directory creation.
Sources: src/main/java/org/example/coding_convention/utils/FileUploadUtil.java:11-23
Cloud Storage Helpers
S3UrlUtils
S3UrlUtils provides specialized parsing logic to decompose S3 identifiers into their constituent "Bucket" and "Key" parts. This is critical for the FileService when updating or retrieving file content directly from S3 using the AWS SDK.
The utility supports three major formats:
- S3 Protocol:
s3://bucket/key - Path-style URLs:
https://s3.region.amazonaws.com/bucket/key - Virtual-hosted-style URLs:
https://bucket.s3.region.amazonaws.com/key
| Method | Input | Output | Description |
|---|---|---|---|
parse(String) | S3 URL or URI | Parts (Record) | Extracts bucket name and object key from various S3 URL formats. |
Sources: src/main/java/org/example/coding_convention/utils/S3UrlUtils.java:10-44
Interaction with Services
These utilities are consumed by the S3UploadService and FileService to facilitate file operations.
This sequence illustrates how utility classes support the high-level file upload and parsing workflow.
Sources: src/main/java/org/example/coding_convention/file/service/S3UploadService.java:27-31, src/main/java/org/example/coding_convention/file/service/FileService.java:49-51
API Configuration Helpers
SwaggerConfig
The SwaggerConfig class serves as a helper for the OpenAPI documentation framework. It centralizes the configuration for API metadata and security schemes, ensuring that the Swagger UI correctly handles JWT authentication.
- Security Scheme: Configures "bearerAuth" using the HTTP Bearer scheme with JWT format.
- Global Requirement: Applies the security requirement globally to all endpoints defined in the Phanes API.
Sources: src/main/java/org/example/coding_convention/config/SwaggerConfig.java:15-27
Data Transfer Objects & Constants
While primarily used for data movement, certain DTOs like EditorDto act as helpers for the WebSocket-based editor by defining structures for line/column ranges.
Range Representation
The EditorDto.Range internal class assists in identifying specific code segments during real-time collaboration.
| Field | Type | Description |
|---|---|---|
startLineNumber | Integer | Starting line of the code selection. |
startColumn | Integer | Starting column of the code selection. |
endLineNumber | Integer | Ending line of the code selection. |
endColumn | Integer | Ending column of the code selection. |
Sources: src/main/java/org/example/coding_convention/websocket/editor/EditorDto.java:7-13
Conclusion
The Utility Classes & Helpers in PhanesEditor-BE provide a robust foundation for handling file metadata, cloud pathing, and API documentation. By isolating logic like S3 URL parsing in S3UrlUtils and path generation in FileUploadUtil, the system maintains a clean separation of concerns, allowing service classes to focus on business logic while relying on these helpers for consistent infrastructure-related operations.