Java SDK tam başvuru

Java 8+ için portalın yerel Maven dağıtımındaki io.sigillum:finans-sdk:0.11.0 bağımlılığını kullanın. Resmî OpenTelemetry ve Jackson bağımlılıkları Maven ile çözülür. Herkese açık depo yayını gerekmez.

Tek multi-release JAR, Java 8 ortak kodunu ve Java 11 HttpClient sınırını içerir. Java 8 HttpURLConnection/HttpsURLConnection kullanır. Gözlem, AI, kaynak, içerik, referans, kapsam, özel OTEL, bağlam ve imzalı teslim sözleşmesi ortaktır. Global OTEL, kurum TLS ayarları ve HTTP proxy değiştirilmez. Ürünün worker’ı Java 8 dahil kendi sabitlenmiş kurulum CA’sını ve sunucu adı kontrolünü kullanır.

<dependency>
  <groupId>io.sigillum</groupId>
  <artifactId>finans-sdk</artifactId>
  <version>0.11.0</version>
</dependency>

Servisin config/2 yapılandırmasındaki kimlik bilgisi kurum/ortam/servisi belirler. Uygulama, gerçek giriş eşleşmesi veya doğrulanmış gelen bağlamdan gelir. scopeTrust her başlangıçta ve gelen bağlamda imzalı kapsamı doğrular. Profil gerçek uygulama/kök ve seçilen servisleri içerir. Worker aynı HTTPS kökeninden 30 saniyede bir yeniler; iş yolunda bekleme yoktur. Doğrulanmış güncelleme tek görüntü olarak uygulanır. Geri sürüm veya aynı sürümde çelişki varsa önceki profil korunur. Başlamış işlem ilk imzalı kapsamıyla sürer.

config/2 dosyasında ürünün yerel aktarım ajanı seçilebilir:

"localTransfer": {
  "endpoint": "http://127.0.0.1:29520",
  "token": "<32-to-256-printable-ASCII-characters-without-spaces>"
}

Açık port ve tam IPv4 loopback kökenini kullanın. Yol, son eğik çizgi, sorgu, fragment veya kullanıcı bilgisi bulunmamalıdır. localhost, diğer adresler, yönlendirmeler ve uygulama proxy ayarları bu sınırda kullanılmaz. Yerel mod seçilmişse ajan kapalıyken bile uzak aktarıma dönüş yoktur. Alan yoksa doğrudan HTTPS/SFREC001 sürer.

İş çağrıları yalnız sınırlı RAM görüntüsü kabul eder. Worker SFRAW001 üretip /v1/captures adresine gönderir. Ajan özet/referans üretir, SFREC001 paketler, kalıcı yeniden denemeyi şifreler ve üst sisteme iletir. Özgün sayısal metin, ekler, kimlik ve ilişkiler korunur. Aynı paket tekrar denenir; yalnız tam token doğrulamalı sigillum.local-handoff/1 alındısından sonra RAM bırakılır. diagnostics().localDurableRecords() yerel teslimi; delivered() uzak teslimi sayar. Yerel teslim uzak sayacı artırmaz. Alındı öncesi kapanma veya doygunluk tam kayıt olarak gösterilmez.

Yerel gönderim hatası, küçük rastgele sapmalı üstel beklemeyi tüm endpoint için uygular. İlk gecikme retryDelayMs, üst sınır 30 saniye veya daha büyük yapılandırılmış değerdir; yapılandırma en çok 300 saniyeye izin verir. Yeni paketler beklemeyi atlamaz. Geçerli alındı beklemeyi sıfırlar; doğrudan HTTPS politikası değişmez. Profiller yalnız kimlik doğrulamalı /v1/profiles üzerinden, mevcut imza ve ileri sürüm kontrolleriyle yenilenir. Paketleme, hash, MAC, ağ ve teslim worker işidir.

import io.sigillum.finans.Sigillum;
import java.nio.file.Paths;

Sigillum sigillum = Sigillum.start(
    Paths.get("C:/application/.sigillum/config.json"));

start(Path), dosya, sertifika, OTEL ve aktarım hazırlığını worker’a planlar. Mutlak yol zorunludur; çalışma dizininde arama veya ek HTTP profili yoktur. Hatalar diagnostics() içinde kalır.

Desteklenen JDK sınırlarını bir kez sarın:

httpServer.createContext("/process", sigillum.httpHandler(nativeHandler));
HttpURLConnection connection = sigillum.httpConnection(nativeConnection);

Java 11+ httpClient(nativeHttpClient) senkron/asenkron API’yi korur. httpConnection; doğal zaman aşımı, proxy, TLS factory, hostname verifier, istek ayarı ve HTTPS alt tipini korur. İçerik önceden okunmaz. Servlet için javax veya Jakarta paketinden yalnız uygun olanı seçin.

Gelen wrapper tam giriş tanımıyla eşleşir veya geçerli x-sigillum-context’i sürdürür. Giden wrapper traceparent/tracestate, global OTEL ve mevcut uygulama başlıklarını değiştirmez. Çelişkiler korunur ve bildirilir. SDK’sız bileşende bağlam ancak gerçekten taşınırsa sürer.

Paylaşılan serviste SDK bir kez kurulur. Gelen imzalı kapsam servisi dışlıyorsa yerel span, HTTP, OTEL veya özel gözlem üretilmez; doğrulanmış bağlam sonraki servise değişmeden aktarılır. Yeni bağlanan uygulama aynı SDK ve servis kimliğiyle çalışabilir. Bilinçli dışlama teslim hatası veya yakalama kaybı değildir.

Zamanlanmış işte tanımlı işlem adını kullanın:

try (ObservationScope execution = sigillum.begin("daily-calculation");
     Sigillum.Binding current = execution.activate()) {
    nativeCalculation();
}

HTTP metaverisi, gerçek parçalar, yaşam döngüsü ve özel OTEL desteklenen sınırlarda otomatiktir. Doğal stream veya publisher/subscriber tüketimi gözlenir; ön okuma ve tekrar çağrı yoktur. Değer, hata, interruption, cancellation ve stream sahipliği korunur. Asenkron çağrı özgün future’ı döndürür; yeniden sarma veya ikinci iptal yapmaz.

Okunmamış gelen gövde yalnız HTTP/1.0/1.1 çerçevelemesi içerik olmadığını kanıtlarsa, gözlenmiş parça/kayıp da yoksa tam ve boş kabul edilir. Transfer-Encoding olmamalı, Content-Length yok veya tek geçerli sıfır olmalıdır. HTTP metodu yetmez. Çelişkili başlıklar, HTTP/2/3 ve bilinmeyen protokol doğal tüketim tamamlanana kadar eksik kalır. SDK bu amaçla okumaz/geri sarmaz.

HttpsExchange ve TLS oturumu korunur. Başarılı stream reset/değiştirme, EOF sonrasında bile kısmi kayıt üretir. Reddedilen reset özgün hatayı korur ve tamlık durumunu değiştirmez.

Hazır UTF-8 JSON nesnelerini kullanın. Sayısal metin, null/eksik alan farkı ve özgün baytlar korunur. SDK reflection ile nesne veya tembel sonuç gezmez. Nesne/UTF-8/tekrarlı alan denetimi worker’da yapılır. true yalnız RAM kabulüdür. Sonradan geçersiz çıkan veri atlanır ve aynı işleme sınırlı kayıp bildirimi eklenir; close() sonrası önceden kabul edilen iş boşaltılırken de geçerlidir.

sigillum.ai("model", modelJson);
sigillum.ai("classification", classificationJson);
sigillum.ai("retrieval", retrievalJson);
sigillum.ai("tool", toolJson);
sigillum.ai("embedding", embeddingJson);
sigillum.ai("inference", inferenceJson);
sigillum.ai("evaluation", evaluationJson);
sigillum.ai("policy", policyJson);
sigillum.ai("explanation", actualSourceExplanationJson);

capture(context, family, kind, schema, rawJson, contents...) yedi aileyi destekler: lifecycle, ai, http, otel, context, source, custom. CaptureContent(id, mediaType, purpose, bytes) gerçek anlamıyla özgün içeriği taşır. Basit map biçimi purpose olarak gözlem türünü, mediaType olarak application/octet-stream kullanır.

Gerçek ilişkiler için en çok 128 SpanLink taşıyan hazır diziyi verin:

sigillum.capture("custom", "decision-inputs", knownJson,
    new SpanLink[] { new SpanLink(actualTraceId, actualSpanId, "parallel-result") });

Kimlikler sıfır olmayan küçük harfli trace/span değerleri, relation boş olmayan en çok 64 UTF-16 birimidir. Bütçe kabulünden sonraki dizi görüntüsü korunur; kaynak dizinin sonradan değiştirilmesi kaydı değiştirmez.

observe(operation, inputJson, nativeCall, rawOutput) gerçek çağrıyı bir kez yürütür; özgün dönüş referansı veya hatayı korur. Yalnız verilen ham girdi/çıktıyı kaydeder. Açıklama veya gizli model içeriği üretilmez. İsteğe bağlı referanslar işlem oluşturmaz veya birleştirmez:

ObservationContext enriched = sigillum.withReferences(sigillum.current(),
    new References(sessionReference, personReference,
        Collections.singletonList(new References.External("institution-trace", correlationId))));
try (Sigillum.Binding current = sigillum.activate(enriched)) {
    nativeWork();
}

Executor sınırında wrap(Runnable)/wrap(Callable) veya callback içinde activate(context) kullanın. Önceki bağlam geri yüklenir. child(context, name) gerçek alt span üretir. exportContext/importContext HTTP wrapper’larıyla aynı imzalı taşıyıcıyı kullanır. Geçersiz bağlamdan uygulama/üst adım uydurulmaz.

ObservationScope.span() gerçek özel OTEL span’ını; tracer() aynı özel sağlayıcıyı açar. Resmî attribute/event/link/status API’leri kullanılabilir. Açık native alt span gerçek parent’ına bağlanmalıdır. Global sağlayıcı veya Context.current() değiştirilmez.

Varsayılan toplam bütçe kodlanmış bekleyen paket dahil 64 MiB ve 1024 kayıttır. İş çağrıları disk, ağ, alındı, flush veya worker kapanmasını beklemez. close() yeni yakalamayı durdurur; worker’ı join etmez. Süreç yaşarken kalan iş boşalabilir; daemon worker süreç çıkışını engellemez.

Worker HTTPS aktarım servisine SFREC001 gönderir; yeniden denemede aynı baytlar ve teslim kimliği kullanılır. Kuyruktan çıkarma sabitlenmiş P-256 P1363 imzası ile kurum, ortam, servis, teslim, paket özeti ve sıralı kayıt bağlarının tam eşleşmesini gerektirir. Sonrasında ürün aktarım servisi şifreli kalıcı yeniden denemeyi üstlenir. Alındı öncesi RAM kalıcı değildir; ani kapanmada kayıp olabilir. Kapasite dolarsa iş çağrısını durdurmak yerine gözlem kaybı diagnostics ve capture.lossReported ile bildirilir.

Alındısız paket aynı bellek payını tutar. Süresi gelen yeniden denemeler yeni işlerle adil dönüşümlenir. Bir uygulamanın reddedilen teslimi diğerini engellemez. Yanıt/alındı uyuşmazlığı bellek payını bırakmaz.

diagnostics(); hazırlık, kabul/teslim, bekleyen bayt/kayıt, sınırlı kayıp sayaçları ve son gözlemci hata sınıfını verir. Servis sırrı ve özgün içerik içermez.

SDK kaynak dağıtımındaki mvn test; protokol, hatalı alındı/bağlam, gerçek HTTPS yeniden deneme, doğal HTTP davranışı, özel OTEL, eşzamanlılık, kapasite ve bekletmeyen kapanma kontrollerini çalıştırır. Çalışma ortamı testlerinde Java 8/11 JDK ve Java 17 runtime gerekir; sigillum.java8.home, sigillum.java11.home, sigillum.java17.home ile belirtilir. Eksik runtime atlanmaz, testi başarısız yapar. sigillum.runtime.jar son kurulu paketi seçebilir. mvn install normal paketi kurar; mvn -f consumer/pom.xml package bağımsız tüketiciyi oluşturur. Test beklemeleri tüketiciye aittir; SDK başlangıcına veya iş çağrılarına eklenmez.