SDK ל-Java¶

גישה תכנותית ל-HomeCloud מ-Java 17+.

Maven: com.homecloudlab:homecloud-sdk
Package: com.homecloudlab.sdk
ADR: ADR-052

אותן יכולות HomeCloud כמו Python, Node.js ו-Go. ה-API הציבורי אידיומטי ל-Java (HomeCloud.builder(), records, חריגות unchecked) ורשאי להיראות אחרת. ההתנהגות שקולה אלא אם תיעדנו תיקון בטיחות (למשל Java לא מריטריא mq().send אוטומטית).

HomeCloud הוא thread-safe אחרי הבנייה. עשו reuse (למשל Spring @Bean). Login אינטראקטיבי ב-HomeCloudAuth ומחזיר client חדש.

התקנה¶

<dependency>
  <groupId>com.homecloudlab</groupId>
  <artifactId>homecloud-sdk</artifactId>
  <version>0.5.10</version>
</dependency>

עד Maven Central (שער GA ציבורי) מורידים מ-GitHub Packages — ראו את README של Java ל-repository + PAT. Maven Central לא דורש PAT.

יצירת לקוח¶

HomeCloud client = HomeCloud.fromEnv();
client.so().upload("docs", UploadOptions.builder().filePath("./a.txt").key("a.txt").build());

מפתחות מפורשים:

HomeCloud client = HomeCloud.fromCredentials("HCAK...", "secret");

פרופיל ~/.homecloud/credentials:

HomeCloud client = HomeCloud.fromProfile("ci");

קונפיגורציה מתקדמת:

HomeCloud client = HomeCloud.builder()
    .apex("holab.abrdns.com")
    .accessKey("HCAK...", "secret")
    .requestTimeout(Duration.ofSeconds(30))
    .build();

מתוך Function (STS)¶

HomeCloud client = HomeCloud.fromSts(new Sts(
    entry.accessKeyId(),
    entry.secretAccessKey(),
    entry.sessionToken(),
    entry.baseUrl(),
    null,
    "so"
));

Object Storage¶

client.so().putJson("docs", "a.json", Map.of("ok", true));
ObjectHead meta = client.so().headObject("docs", "a.json");

תורים¶

client.mq().send("orders", Map.of("id", 1));
List<Message> msgs = client.mq().receive("orders", new ReceiveOptions(10, 5, false));

send לא מרוטרי על 502/503/504 (בניגוד ל-Python/Node) כדי לא לשכפל הודעות.

משימות ודיאגרמות¶

מישור ניהול — JWT משתמש (HomeCloudAuth.login) או Access Key קשור למשתמש (SigV1).

List<Map<String, Object>> items = client.tasks().search("cert @alice &ops due:overdue");
Map<String, Object> detail = client.tasks().get("TASK-12");
client.tasks().create("Rotate cert", Map.of(
    "type", "change",
    "priority", "p2",
    "assignees", List.of("alice"),
    "label_names", List.of("ops")));
client.tasks().assignMe("TASK-12", "in_progress");
client.tasks().comment("TASK-12", "Deployed to staging");

List<Map<String, Object>> diagrams = client.diagrams().list();
Map<String, Object> doc = client.diagrams().get(diagramId);
client.diagrams().create("Production plan", "Draft", null);
client.diagrams().update(diagramId, Map.of(
    "name", "Prod",
    "document", doc.get("document"),
    "revision", doc.get("revision")));

שגיאות¶

try {
    client.so().headObject("docs", "missing.txt");
} catch (NotFoundException e) {
    System.out.println(e.getResourceType() + " " + e.getResource());
}

משתני סביבה¶

כמו ב-Python: HC_ACCESS_KEY_ID, HC_SECRET_ACCESS_KEY, HC_APEX, HC_PROFILE (וגם HOMECLOUD_*).