ローカルデバッグガイド — Java
This guide covers everything specific to debugging an Extend Service Extension app written in Java. For general debugging concepts — environment setup, VS Code debug workflow, log reading, and common issues — see:
- Extend local debugging guide — common concepts for all Extend app types
- Java language setup guide — Java prerequisites, JVM remote debug, jq, and Java-specific troubleshooting
Project structure
src/
└── main/
├── java/
│ └── com/accelbyte/extend/serviceextension/
│ ├── Application.java # Entry point
│ ├── service/
│ │ └── MyService.java # Your business logic
│ ├── interceptor/
│ │ └── AuthServerInterceptor.java # IAM token and permission validation
│ └── ...
└── proto/
└── service.proto # gRPC API definition
| File | What it does |
|---|---|
Application.java | Entry point — wires gRPC server, gRPC-Gateway, metrics, and auth. |
service/MyService.java | Your business logic — implements the gRPC service methods. |
interceptor/AuthServerInterceptor.java | Validates every incoming request's IAM token and permission. |
proto/service.proto | Defines the gRPC API — endpoints, request/response shapes, and required permissions. |
Port numbers:
| Port | Purpose |
|---|---|
6565 | gRPC server (internal — used by gRPC-Gateway) |
8000 | gRPC-Gateway HTTP/REST — call this from a browser, Postman, or curl |
8080 | Prometheus metrics endpoint (/metrics) |
Running the service locally
From the terminal
# Export all variables from your .env file
export $(grep -v '^#' .env | xargs)
./gradlew bootRun
From VS Code
Use Terminal → Run Task → "Run: Service".
This task is defined in .vscode/tasks.json and loads the .env file for you automatically.
Confirming the service is up
You should see logs like:
{"time":"...","level":"INFO","msg":"app server started","service":"extend-app-service-extension"}
{"time":"...","level":"INFO","msg":"starting gRPC-Gateway HTTP server","port":8000}
{"time":"...","level":"INFO","msg":"serving prometheus metrics","port":8080,"endpoint":"/metrics"}
Open http://localhost:8000<BASE_PATH>/apidocs/ in your browser to verify Swagger UI is live.
Attaching the debugger
VS Code (recommended)
The repository ships with a ready-to-use launch configuration in .vscode/launch.json:
{
"name": "Debug: Service",
"type": "java",
"request": "launch",
"mainClass": "com.accelbyte.extend.serviceextension.Application",
"envFile": "${workspaceFolder}/.env",
"cwd": "${workspaceFolder}"
}
Follow the attaching the debugger steps in the generic guide, then select "Debug: Service" from the dropdown.
Other IDEs — JVM remote debug
Start the app with the JVM debug agent, which listens on port 5005 by default:
export $(grep -v '^#' .env | xargs)
./gradlew bootRun --debug-jvm
Then open your IDE (IntelliJ IDEA, Eclipse) and create a Remote JVM Debug configuration
targeting localhost:5005.
Where to put breakpoints
| What you want to investigate | File and location |
|---|---|
| A specific REST endpoint being called | service/MyService.java — top of the relevant method |
| Auth/token validation failure | interceptor/AuthServerInterceptor.java — the interceptCall method |
| Data not saving or loading correctly | The repository or storage class used in your service |
| Service not starting at all | Application.java — the main method and bean initialization |
For conditional breakpoint syntax, see the Java language guide.
Reading logs
For jq log filtering, see the
Java language guide.
Testing endpoints manually
For curl and grpcurl usage, see
Testing with grpcurl in the generic guide.
For Swagger UI testing (SE-specific), see Testing endpoints manually in the SE main guide.
Java-specific troubleshooting
Proto changes have no effect
Symptom: You edited src/main/proto/service.proto but nothing changed at runtime.
Cause: The generated gRPC stubs have not been rebuilt.
Fix: Run a clean build to trigger the protobuf Gradle plugin:
./gradlew clean build
Gradle daemon issues
If the service behaves inconsistently between runs, stop the Gradle daemon and try again:
./gradlew --stop
./gradlew bootRun
JVM port conflict for remote debugging
See JVM port conflict for remote debugging in the Java language guide.
Checking for port conflicts (service ports)
See Checking for port conflicts in the Java language guide.
AI assistance
The app template ships with a Claude agent skill at
.claude/skills/debugging-guide/SKILL.md.
For AI prompting tips and MCP server details, see Debugging with AI assistance in the generic guide.