GoogleSheetsClient SDK

A Java SDK for interacting with Google Sheets API, designed for seamless integration with Spring applications and deployment to Maven Central.

google-sheets-sdk/
├── .gitignore                      # Bỏ qua target/, .idea/, *.iml
├── LICENSE                         # MIT License
├── README.md                       # Hướng dẫn cài đặt, tích hợp Spring, sử dụng
├── pom.xml                         # Cấu hình Maven
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/thucnh/googlesheetssdk/
│   │   │       ├── client/
│   │   │       │   ├── GoogleSheetsClient.java
│   │   │       │   ├── DataAppender.java
│   │   │       │   ├── DataUpdater.java
│   │   │       │   ├── DataDeleter.java
│   │   │       │   ├── DataReader.java
│   │   │       │   ├── SheetManager.java
│   │   │       │   └── internal/
│   │   │       │       └── SheetsServiceFactory.java
│   │   │       ├── domain/
│   │   │       │   └── SheetData.java
│   │   │       ├── exception/
│   │   │       │   └── GoogleSheetsException.java
│   │   │       ├── util/
│   │   │       │   ├── LockManager.java
│   │   │       │   ├── Validator.java
│   │   │       │   └── EntityMapper.java
│   │   │       ├── config/
│   │   │       │   └── WritePolicy.java
│   │   │       └── mapping/
│   │   │           ├── SheetEntity.java
│   │   │           └── SheetColumn.java
│   │   └── resources/
│   │       └── write-policy.properties # Cấu hình dự phòng
│   └── test/
│       ├── java/
│       │   └── com/thucnh/googlesheetssdk/
│       │       ├── client/
│       │       │   ├── GoogleSheetsClientTest.java
│       │       │   ├── DataAppenderTest.java
│       │       │   ├── DataUpdaterTest.java
│       │       │   ├── DataDeleterTest.java
│       │       │   ├── DataReaderTest.java
│       │       │   └── SheetManagerTest.java
│       │       ├── domain/
│       │       │   └── SheetDataTest.java
│       │       ├── util/
│       │       │   ├── ValidatorTest.java
│       │       │   └── EntityMapperTest.java
│       │       └── mapping/
│       │           └── SheetEntityTest.java
│       └── resources/
│           └── test-credentials.json   # Tệp giả lập kiểm thử
├── docs/
│   ├── api/                            # Javadoc
│   ├── examples/
│   │   ├── GoogleSheetsClientExample.java
│   │   └── SheetEntityExample.java     # Ví dụ dùng findByColumn
│   └── guides/
│       ├── setup-google-cloud.md       # Thiết lập Google Cloud
│       ├── spring-integration.md       # Tích hợp Spring
│       └── handling-errors.md          # Xử lý lỗi
├── scripts/
│   └── deploy.sh                       # Script xuất bản Maven
└── .github/
└── workflows/
└── ci.yml                      # CI/CD

Features

• Entity Mapping: Map Java classes to Google Sheets using @SheetEntity and @SheetColumn.
• CRUD Operations: Append, update, delete, and read data with thread-safety.
• Search: Find data by column value using findByColumn.
• Sheet Management: Auto-create sheets with headers (sheet.ddl-auto=update).
• Spring Integration: Supports Dependency Injection and application.properties.
• Thread-Safety: Uses ReentrantLock for concurrent operations.
• Write Policies: Configurable write policies (STRICT, WARN, OVERRIDE).

Installation

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.thucnh</groupId>
    <artifactId>google-sheets-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Configuration Spring Boot Configure in application.properties:

sheets.credentials-path=/path/to/credentials.json
sheets.spreadsheet-id=your-spreadsheet-id
sheets.write-policy=WARN
sheets.write-warn-verbose=true
sheets.ddl-auto=update

Non-Spring Projects Place write-policy.properties in src/main/resources/:

sheets.write-policy=STRICT
sheets.write-warn-verbose=true
sheets.ddl-auto=update

Usage

Example: Mapping a Sheet

@SheetEntity(name = "Users")
public class UserSheet {
    @SheetColumn(name = "A")
    private String name;
    @SheetColumn(index = 1)
    private int age;
}

Example: CRUD and Search

Initialize client

GoogleSheetsClient client = new GoogleSheetsClient(sheetsService, spreadsheetId, validator);

Append data

UserSheet user = new UserSheet();
user.setName("An");
user.setAge(25);
client.appendData(UserSheet.class, user);

Find by column value

List<UserSheet> users = client.findByColumn(UserSheet.class, "name", "An");

Read data

List<UserSheet> allUsers = client.readData(UserSheet.class, "Users!A:B");

Update data

client.updateData(UserSheet.class, user, "Users!A2:B2");

Delete data

client.deleteData(UserSheet.class, "Users!A2:B2");

Spring Integration

Use @Autowired to inject GoogleSheetsClient:
@Service
public class UserService {
    @Autowired
    private GoogleSheetsClient client;

    public List<UserSheet> findUsersByName(String name) {
        return client.findByColumn(UserSheet.class, "name", name);
    }
}

Documentation

Next Steps

• See docs/guides/setup-google-cloud.md setup-google-cloud credentials.
• See docs/examples/GoogleSheetsClientExample.md for examples Client.
• See docs/examples/SheetEntityExample.md for examples Sheet.
• See docs/guides/spring-integration.md for Spring Boot setup.
• Check docs/guides/ for error handling.

License MIT License. See LICENSE for details.