# Java Jakarta Servlet başvurusu

Güncel SDK paketindeki tam kullanım sözleşmesi: kurulum, bütün açık yüzeyler, sınırlar ve hata davranışı. Kaynak metnin dili korunmuştur.

## Paket ve temel kullanım

jakarta.servlet 5/6 için io.sigillum:finans-sdk-jakarta-servlet:0.11.0 kullanın. Adaptör Java 8 bytecode hedefler; çalışma ortamını uygulama ve framework belirler. Spring 6 Java 17 gerektirir. Yalnız uygulamanın Servlet ad alanıyla eşleşen adaptörü kurun. Çekirdek SDK, özel OTEL ve normal bağımlılıklar Maven’dan çözülür. Servlet API’sini uygulama/container sağlar.

## Spring Boot / Spring MVC

Uygulamanın mevcut bağımlılık enjeksiyonu ve filtre kaydını kullanın:

```java
@Bean(destroyMethod = "close")
public Sigillum sigillum() {
    return Sigillum.start(Paths.get(".sigillum/config.json").toAbsolutePath());
}

@Bean
public FilterRegistrationBean<SigillumJakartaServletFilter> sigillumFilter(Sigillum sdk) {
    FilterRegistrationBean<SigillumJakartaServletFilter> registration =
        new FilterRegistrationBean<>(new SigillumJakartaServletFilter(sdk));
    registration.setAsyncSupported(true);
    registration.setDispatcherTypes(DispatcherType.REQUEST, DispatcherType.ASYNC,
        DispatcherType.ERROR);
    registration.addUrlPatterns("/*");
    return registration;
}
```

Gerekli import’lar: io.sigillum.finans.Sigillum, io.sigillum.finans.SigillumJakartaServletFilter, java.nio.file.Paths, jakarta.servlet.DispatcherType, org.springframework.context.annotation.Bean ve org.springframework.boot.web.servlet.FilterRegistrationBean.

REQUEST, ASYNC ve ERROR dispatch türleri ile async desteğini açın. Filtreyi tüketimini gözlemek istediğiniz bileşenden önce yerleştirin. Kimlik doğrulama/güvenlik filtrelerini veya framework executor’larını değiştirmeyin. Boot 3+/Jakarta için Jakarta sınıfı ve ad alanı kullanılır.

## Standart WAR kaydı

Parametresiz kurucu normal web.xml kaydını destekler:

```xml
<filter>
  <filter-name>sigillum</filter-name>
  <filter-class>io.sigillum.finans.SigillumJakartaServletFilter</filter-class>
  <async-supported>true</async-supported>
  <init-param>
    <param-name>configPath</param-name>
    <param-value>/app/.sigillum/config.json</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>sigillum</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>ASYNC</dispatcher>
  <dispatcher>ERROR</dispatcher>
</filter-mapping>
```

Yapılandırmanın gerçek mutlak yolunu kullanın. Eksik, bozuk veya erişilemeyen yapılandırma gözlemi devre dışı bırakır; uygulamanın başlamasını ve istek sunmasını engellemez. Filtre yalnız kendisinin oluşturduğu SDK’yı kapatır. İş kodu aynı SDK ile AI/özel kayıt gönderecekse bağımlılık enjeksiyonu kaydını kullanın.

## Yakalanan bilgiler ve sınırlar

Filtre tanımlı kökleri veya doğrulanmış devamları gözlemler: metot, URI, tekrar eden başlıklar, gözlenen yanıt durumu, tüketilen istek baytları, başarılı yanıt yazmaları, asenkron dispatch/bitiş, doğal stream hataları ve özel OTEL yaşam döngüsü. Uygulamanın kapsamı dışındaki servis kendi kaydını üretmeden geçerli bağlamı taşır. Gövde uygulama adına önceden okunmaz, geri sarılmaz veya tamponlanmaz; stream otomatik flush edilmez.

Reader/PrintWriter içeriği applicationText, contentEncoding=UTF-16BE, sourceCharacterEncoding ve byteCoordinate=storedContent ile raporlanır. Bunlar bölünmüş veya eşleşmeyen surrogate dahil gerçek gözlenen UTF-16 birimleridir; ağ baytı oldukları iddia edilmez. İçerik türü text/plain;charset=UTF-16BE olur. Tamlık gözlenen mantıksal içerik içindir, uzaktaki istemciye ağ teslimi için değildir.

PrintWriter metotları, auto-flush, hatalar ve fluent dönüşler korunur. Object/Formattable dönüşümleri iki kez çalıştırılmaz; printf/format ikinci biçimlendiriciyle yeniden yürütülmez. Böyle çıktılar, özgün writer döndüren zincirli çağrılar, silinen tamponlar, doğal parametre/multipart ayrıştırma, atlanan girdi ve satır ayıracını gizleyen okuyucular kısmi işaretlenir.

AsyncContext.start, nonblocking listener, tekrarlı async döngü ve Spring MVC Callable yalnız SDK bağlamını bağlar/geri yükler. Spring varsa resmî WebAsyncManager interceptor API’si kullanılır. Executor, diğer interceptor’lar, global OTEL ve zamanlama değiştirilmez. Bağımsız görev veya dışarıda üretilen DeferredResult için gerçek planlama sınırında sdk.wrap(...) kullanın; eksik bağlam tahmin edilmez.

Yakalama ve callback hataları iş çağrısına taşınmaz. Teslim ve profil yenileme worker’da yürür. Filtre kapanışı flush veya kalıcı teslim beklemez.