Kuyruk oluşturma ve mesajı kuyruktan teslim etme

Bu rehber, orders.incoming adlı kalıcı bir iş kuyruğu oluşturur, gelen mesajı önce bu kuyruğa yazan ve ardından hedef sisteme teslim eden iki akış kurar. Örnekleri geliştirme ortamında, size ayrılmış kuyruk ve kullanıcıyla uygulayın. Teslim edilemeyen mesajın ne olduğunu asenkron mesajların sorumluluğu ve dead letter’lar açıklar.

Önkoşullar

• Kurulumda erişilebilir Artemis broker’ı ve yapılandırılmış Artemis console bağlantısı.
• Konsol yönetimi için platform-admin yetkisi. Yalnız platform-user veya platform-developer rolü konsol yönetimi sağlamaz.
• Proje düzenleme/çalıştırma yetkisi ve broker’a bağlanabilen runtime ağı.
• Broker mesajlaşma kullanıcısı ve parolası. Konsola OIDC ile giriş yapmak JMS bağlantısını bearer token ile yetkilendirmez.
• İstemci bağımlılığı ve parolayı okuyabilecek Secret yetkisi.

Yerel kurulumda runtime’dan broker adresi tcp://artemis:61616 olabilir. Müşteri broker’ı kullanıyorsanız kendi DNS, port ve TLS ayarınızı alın. Browser’ın broker konsolunu açabilmesi, runtime’ın mesaj portuna erişebildiği anlamına gelmez.

Kalıcı kuyruk oluşturun

1. Lunex sol menüsünden Artemis console açın. Bağlantı görünmüyorsa yönetici konsol adresini yapılandırmalıdır.
2. Artemis JMX içinde ağacı genişletip Broker düğümünü seçin.
3. Operations bölümündeki createQueue(String) işleminin Details alanını açın.
4. queueConfiguration alanına aşağıdaki JSON’u girip işlemi yürütün:

{
  "name": "orders.incoming",
  "address": "orders.incoming",
  "routing-type": "ANYCAST",
  "durable": true,
  "auto-create-address": true
}

5. Artemis → Queues içinde kuyruğu bulun. Adres, yönlendirme türü, kalıcılık ve mesaj sayısını kontrol edin.

Beklenen sonuç, orders.incoming adresine bağlı aynı adlı kalıcı kuyruktur. Ad zaten varsa yeni bir kuyruk oluşturmak yerine mevcut tanımı ve sahibiyle olan kullanım sözleşmesini kontrol edin.

Projeye broker bağlantısını ekleyin

1. System → Secrets bölümünde mesajlaşma kullanıcı bilgilerinizi bir Secret’ta tutun. Örnekte orders-broker Secret’ının username ve password anahtarları kullanılır.
2. Projenin Architecture → More create options → Bean işlemini açın.
3. Type → Messaging, Template → JMSArtemis seçin.
4. Name değerini ordersBroker yapın. Şablondaki örnek kullanıcı/parolayı gerçek Secret referanslarınızla değiştirin; bunlar çalışan hesabınız değildir.
5. Bean’i örneğin broker.camel.yaml dosyasına kaydedin.
6. application.properties içindeki mevcut camel.jbang.dependencies listesine mvn:org.apache.activemq:artemis-jakarta-client-all:2.56.0 ekleyin. Mevcut bağımlılıkları koruyun; virgülle ayırın.

Bağlantı YAML’ı:

- beans:
    - name: ordersBroker
      type: '#class:org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory'
      properties:
        brokerURL: '{{orders.broker.url}}'
        user: '{{secret:orders-broker/username}}'
        password: '{{secret:orders-broker/password}}'
        consumerWindowSize: 0

application.properties örneği:

orders.broker.url=tcp://artemis:61616
camel.jbang.dependencies=camel-console,mvn:org.apache.activemq:artemis-jakarta-client-all:2.56.0

consumerWindowSize: 0, tüketicinin broker’dan mesajları önceden almasını kapatır. Önceden alınmış mesajlar, yeniden teslim için bekleyen bir mesajın arkasında bekler; bu ayar kuyruktaki diğer mesajların gecikmeden işlenmesini sağlar. Çok yüksek hacimli ve gecikmeye duyarsız kuyruklarda varsayılan pencere verimi artırabilir.

Mesajı park edebilmek için Artemis JMS istemcisini kullanın. AMQP bağlantısı da broker’a bağlanır, ancak AMQP istemcisiyle tüketilen mesaj park edilemez. Bir bağlantı adını değiştirdiğinizde ona referans veren endpoint’leri de güncelleyin.

Mesajı önce saklayın, sonra teslim edin

Kaynak sistem mesajı teslim ettiğinde işini bitmiş sayar. Lunex mesajı ancak kalıcı bir kuyruğa yazdıktan sonra onaylamalı ve hedefe ayrı bir akışla teslim etmelidir. Böylece hedef kapalıyken veya Lunex yeniden başlarken mesaj kaybolmaz.

Kabul akışı

Kaynak sistem Lunex API’sini çağırıyorsa, işlemin route’u mesajı kuyruğa yazar ve ancak yazma başarılı olduğunda yanıt döner. Kaynak sistem mesajı doğrudan Artemis’e gönderiyorsa bu akışa gerek yoktur; broker’ın onayı aynı işi görür.

- route:
    id: accept-order
    from:
      uri: direct:acceptOrder
      steps:
        - to:
            uri: sjms2:queue:orders.incoming
            parameters:
              connectionFactory: '#ordersBroker'
              deliveryPersistent: true
              exchangePattern: InOnly
        - setHeader:
            name: CamelHttpResponseCode
            constant: 202

deliveryPersistent: true ile gönderim, broker mesajı kalıcı olarak yazana kadar bekler. Yazma başarısız olursa route hata alır ve kaynak sistem hatayı görür; mesaj sessizce kaybolmaz.

Teslim akışı

deliver-orders.camel.yaml içine aşağıdaki akışı ekleyin. sjms2 standart mesajlaşma bileşenidir; connectionFactory aynı projedeki bağlantı bean’ini seçer.

- route:
    id: deliver-orders
    description: Deliver queued orders
    from:
      uri: sjms2:queue:orders.incoming
      parameters:
        connectionFactory: '#ordersBroker'
        transacted: true
      steps:
        - setProperty:
            name: lunex.monitor.applicationId
            simple: "${header.OrderId}"
        - bean:
            ref: lunexMonitor
            method: "appendBusinessValue('Order',${header.OrderId})"
        - to:
            uri: direct:sendOrderToTarget

direct:sendOrderToTarget, siparişi hedef sisteme gönderen kendi route’unuzdur. transacted: true, teslim akışı başarıyla bittiğinde mesajı kuyruktan siler. Akış hata fırlatırsa teslim geri alınır ve broker mesajı daha sonra yeniden verir. Bu yüzden hedef sistemden gelen hatayı handled olarak bitirmeyin; ya fırlatın ya da park edin. Mesaj yeniden verilmeden önce akışın içindeki ara adımlar tekrar çalışır.

1. Projede Log level → Info seçin ve Run kullanın.
2. Log sekmesinde bağlantı ve route başlangıcını kontrol edin.
3. Broker’da tüketici sayısının arttığını doğrulayın.
4. Kabul akışını çağırın veya bir test akışından OrderId header’ı olan örnek bir mesajı kabul akışındaki üretici adımıyla gönderin.
5. Broker’da eklenen ve onaylanan mesajları, Lunex’te ise Application ID ile çalışma sonucunu kontrol edin.

Beklenen sonuç, tüketici çalışırken mesajın işlenmesi ve bekleyen mesaj sayısının düşmesidir.

Teslim garantileri

• En az bir kez: Hedef mesajı kabul ettikten sonra onay kaybolursa aynı mesaj yeniden işlenir. Hedef tarafta iş anahtarıyla tekrarı tanıyın veya işlemi tekrar güvenli hale getirin.
• Sıra korunmaz: Yeniden teslim bekleyen bir mesaj beklerken kuyruktaki sonraki mesajlar işlenir. Sıraya bağlı bir arayüz tasarlamayın.

Yeniden teslim

İki farklı yeniden deneme düzeyi vardır. Akışın yerel hata politikası başarısız adımı aynı run içinde tekrar deneyebilir. Broker ise geri alınan teslimi yeni teslim olarak tekrar verir. Bu iki sayıyı birlikte seçin; aksi halde bir uzak çağrı beklediğinizden çok daha fazla çalışabilir.

Paket içindeki broker’da yeniden teslim kurulumda bütün kuyruklar için tanımlıdır; konsolda ayarlanmaz. Geri alınan teslim varsayılan olarak 1 dakika sonra, sonra her seferinde iki kat (en çok 30 dakika) beklenerek yeniden verilir. Her bekleme %15’e kadar rastgele sapar; bir kesintiden sonra bekleyen mesajlar hedefe aynı anda gitmez. 30. başarısız teslimden sonra, yaklaşık 12,5 saat içinde, mesaj bir dead letter olur ve silinene kadar saklanır. Değerleri yönetici kurulum rehberindeki ayarlarla değiştirir. Yeniden teslim ve dead-letter yapılandırması broker davranışını açıklar.

Kuyruğu inceleyin

Artemis → Queues içinden kuyruğu seçip mesajları ve broker istatistiklerini inceleyin. JMX ağacındaki kuyruk Operations işlemleri de kullanılabilir:

Buradaki sayısal broker messageID, Lunex Message ID veya JMS mesaj kimliğiyle aynı alan değildir. İşlem öncesinde kuyruktan okuduğunuz broker kimliğini kullanın. Toplu işlemlerde boş filtre bütün mesajları kapsayabilir. Silme/purge işlemleri mesajları işleyerek tamamlamaz ve Lunex’te kayıt bırakmaz. Artemis kuyruk işlemleri parametreleri tanımlar.

Sorun giderme