Azure Service Bus JMS 2.0 geliştirici kılavuzu

Bu kılavuz, Java İleti Hizmeti (JMS) 2.0 API'sini kullanarak Azure Service Bus ile iletişimde başarılı olmanıza yardımcı olacak ayrıntılı bilgiler sağlar.

Java geliştiricisi olarak, Azure Service Bus'ı kullanmaya yeni başladıysanız aşağıdaki makaleleri okumayı göz önünde bulundurun.

Başlangıç Yapmak Kavramlar

Java İleti Hizmeti (JMS) programlama modeli

Java İleti Hizmeti API programlama modeli aşağıdaki bölümlerde açıklanmıştır:

Uyarı

Azure Service Bus Premium katmanı JMS 1.1 ve JMS 2.0'ı destekler.

Azure Service Bus - Standart katman sınırlı JMS 1.1 işlevselliğini destekler. Diğer ayrıntılar için bu belgelere bakın.

JMS - Yapı taşları

JMS uygulamasıyla iletişim kurmak için aşağıdaki yapı taşları kullanın.

Uyarı

Bu kılavuz, Oracle Java EE 6 Java İleti Hizmeti (JMS) öğreticisinden uyarlanmıştır.

Java İleti Hizmeti'ni (JMS) daha iyi anlamak için bu öğreticiye bakın.

Bağlantı fabrikası

Uyarı

Kitaplık azure-servicebus-jms iki çeşitle kullanılabilir: com.azure:azure-servicebus-jmsJakarta EEjakarta.jms.* () için (sürüm 2.0.0+) ve com.microsoft.azure:azure-servicebus-jmsJava EEjavax.jms.* () için (sürüm 1.0.x). Doğru yapıtı seçme konusunda rehberlik için bkz. Jakarta EE ve javax desteği.

İstemci, JMS sağlayıcısına bağlanmak için bağlantı fabrikası nesnesini kullanır. Bağlantı fabrikası, yöneticinin tanımladığı bir dizi bağlantı yapılandırma parametresini kapsüller.

Her bağlantı fabrikası , ConnectionFactoryveya QueueConnectionFactory arabiriminin TopicConnectionFactorybir örneğidir.

Azure Service Bus bağlanmayı kolaylaştırmak için bu arabirimler sırasıyla ServiceBusJmsConnectionFactory, ServiceBusJmsQueueConnectionFactory veya ServiceBusJmsTopicConnectionFactory aracılığıyla uygulanır.

Önemli

JMS 2.0 API'sini kullanan Java uygulamaları, Azure Service Bus'a bağlantı dizesi kullanarak veya Microsoft Entra destekli kimlik doğrulamasından yararlanmak için TokenCredential kullanarak bağlanabilir. Microsoft Entra destekli kimlik doğrulamasını kullandığınızda, gerektiğinde kimliğe gerekli rol ve izinler atadığınızdan emin olun.

Azure'da sistem tarafından atanan bir yönetilen kimlik oluşturun ve oluşturmak için TokenCredentialbu kimliği kullanın.

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

Bağlantı fabrikasını aşağıdaki parametrelerle başlatabilirsiniz:

  • Belirteç kimlik bilgisi - OAuth belirteci sağlayabilen bir kimlik bilgilerini temsil eder.
  • Azure Service Bus Premium katmanı ad alanının ana bilgisayar ismi.
  • ServiceBusJmsConnectionFactorySettings özellik paketi, şunları içerir:
    • connectionIdleTimeoutMS - milisaniye cinsinden boşta bağlantı zaman aşımı.
    • traceFrames - AMQP izleme çerçevelerini hata ayıklama için toplamak amacıyla boolean bayrağı.
    • Diğer yapılandırma parametreleri.

Aşağıdaki örnekte gösterildiği gibi fabrikayı oluşturun. Jeton kimlik bilgileri ve sunucu gerekli parametrelerdir, ancak diğer özellikler isteğe bağlıdır.

String host = "<YourNamespaceName>.servicebus.windows.net";
ConnectionFactory factory = new ServiceBusJmsConnectionFactory(tokenCredential, host, null);

JMS hedefi

Hedef, istemcinin ürettiği iletilerin hedefini ve kullandığı iletilerin kaynağını belirtmek için kullandığı nesnedir.

Hedefler Azure Service Bus'taki varlıklarla eşleniyor - kuyruklar (noktadan noktaya senaryolarda) ve konular (pub-sub senaryolarında).

Bağlantılar

Bağlantı, bir JMS sağlayıcısıyla sanal bağlantıyı kapsüller. Azure Service Bus, uygulama ile Azure Service Bus arasında AMQP üzerinden, durum bilgisi taşıyan bir bağlantıyı temsil eder.

Aşağıdaki örnekte gösterildiği gibi bağlantı fabrikasından bir bağlantı oluşturun:

Connection connection = factory.createConnection();

Oturumlar

Oturum, mesajların üretilip tüketilmesi için tek bir işlem ve bağlam sunar. Bunu, mesajlar, mesaj üreticileri ve tüketicileri oluşturmak için kullanın. Ayrıca atomik bir iş birimine gönderme ve alma işlemlerini gruplandırmak için işlem bağlamı sağlar.

Aşağıdaki örnekte gösterildiği gibi bağlantı nesnesinden bir oturum oluşturun:

Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);

Uyarı

JMS API,mesajlaşma oturumlarının etkinleştirildiği hizmet veri yolu kuyruklarından veya konu başlıklarından ileti almayı desteklemez.

Oturum modları

Aşağıdaki modlardan herhangi biriyle oturum oluşturun.

Oturum modları Davranış
Oturum.OTOMATİK_ONAYLA Oturum, istemcinin bir mesajı aldığını, ya bir alma çağrısından başarıyla döndüğünde ya da oturumun mesajı işlemeye çağırdığı dinleyici başarıyla döndüğünde otomatik olarak onaylar.
Session.CLIENT_ACKNOWLEDGE İstemci, iletinin onaylama yöntemini çağırarak işlenmiş iletiyi kabul eder.
Session.DUPS_OK_ACKNOWLEDGE Bu bildirim modu, oturuma mesajların teslimini tembel bir şekilde kabul etme talimatı verir.
Session.SESSION_TRANSACTED Oturumun yerel bir işlem kullanması gerektiğini belirtmek için bu değeri Connection nesnesinin metot createSession(int sessionMode)'a bağımsız değişken olarak geçirin.

Oturum modunu belirtmezseniz varsayılan ayar Session.AUTO_ACKNOWLEDGE.

JMSContext

Uyarı

JMSContext, JMS 2.0 belirtiminin bir parçası olarak tanımlanır.

JMSContext, bağlantı ve oturum nesnesi tarafından sağlanan işlevselliği birleştirir. Bunu bağlantı fabrikası nesnesinden oluşturursunuz.

JMSContext context = connectionFactory.createContext();

JMSContext modları

Session nesnesi gibi JMSContext'i de Oturum modlarında bahsedilen onay modlarıyla oluşturabilirsiniz.

JMSContext context = connectionFactory.createContext(JMSContext.AUTO_ACKNOWLEDGE);

Bir mod belirtmezseniz varsayılan ayar JMSContext.AUTO_ACKNOWLEDGE.

JMS ileti üreticileri

İleti üreticisi, JMSContext veya Session kullanarak oluşturduğunuz bir nesnedir. Bir hedefe ileti göndermek için bunu kullanın.

Aşağıdaki örnekte gösterildiği gibi tek başına nesne olarak oluşturabilirsiniz:

JMSProducer producer = context.createProducer();

Ya da bir ileti göndermeniz gerektiğinde çalışma zamanında oluşturabilirsiniz.

context.createProducer().send(destination, message);

JMS ileti tüketicileri

İleti tüketicisi, JMSContext veya Session tarafından oluşturulan bir nesnedir. Hedefe gönderilen iletileri almak için bunu kullanın. Aşağıdaki örnekte gösterildiği gibi oluşturun:

JMSConsumer consumer = context.createConsumer(dest);

receive() metodu ile eşzamanlı alımlar

İleti tüketicisi, receive() yöntemi ile hedeften senkron bir şekilde ileti almak için bir yol sağlar.

Bağımsız değişkenler veya zaman aşımı belirtmezseniz veya bir zaman aşımı 0belirtirseniz, ileti ulaşmadığı veya bağlantı kesilmediği sürece (hangisi daha önceyse) tüketici süresiz olarak engeller.

Message m = consumer.receive();
Message m = consumer.receive(0);

Sıfır olmayan pozitif bir bağımsız değişken sağladığınızda, istemci bu süre ölçerin süresi dolana kadar bekler.

Message m = consumer.receive(1000); // time out after one second.

JMS ileti dinleyicileriyle zaman uyumsuz mesaj alma

İleti dinleyicisi, hedefteki iletilerin zaman uyumsuz işlenmesi için kullandığınız bir nesnedir. Belirli bir iş mantığının bulunduğu MessageListener yöntemini içeren onMessage arabirimini uygular.

setMessageListener yöntemini kullanarak bir ileti dinleyici nesnesinin örneğini oluşturmanız ve onu belirli bir ileti tüketicisine kaydetmeniz gerekir.

Listener myListener = new Listener();
consumer.setMessageListener(myListener);

Konu başlıklarından kullanma

JMS İleti Tüketicilerini, kuyruk veya konu şeklindeki bir hedef için oluşturursunuz.

Kuyruklardaki tüketiciler, istemci uygulaması ile Azure Service Bus arasındaki Oturum (ve Bağlantı) bağlamında yaşayan istemci tarafı nesneleridir.

Ancak konularla ilgili tüketicilerin iki bölümü vardır:

  • Oturum (veya JMSContext) bağlamında bulunan bir istemci tarafı nesnesi ve
  • Azure Service Bus üzerinde bir varlık olan abonelik.

Abonelikler burada belgelenmiştir ve aşağıdaki türlerden biri olabilir:

  • Paylaşılan dayanıklı abonelikler
  • Paylaşılan geçici abonelikler
  • Paylaşılmayan dayanıklı abonelikler
  • Paylaşılmayan dayanıklı olmayan abonelikler

JMS Kuyruk Tarayıcıları

JMS API'si, uygulamanın kuyruktaki iletilere göz atmak ve her ileti için üst bilgi değerlerini görüntülemek için kullanabileceği bir QueueBrowser nesne sağlar.

Aşağıdaki örnekte gösterildiği gibi JMSContext kullanarak bir Kuyruk Tarayıcısı oluşturabilirsiniz:

QueueBrowser browser = context.createBrowser(queue);

Uyarı

JMS API bir konuya göz atmak için bir API sağlamaz.

Bu sınırlama, konunun kendisi iletileri depolamadığından oluşur. İleti, konuya gönderilir gönderilmez uygun aboneliklere yönlendirilir.

JMS ileti seçicileri

Alma uygulamaları, aldıkları iletileri filtrelemek için ileti seçicileri kullanabilir. İleti seçicileri kullanarak, alıcı uygulama iletileri filtreleme işini bu sorumluluğu almak yerine JMS sağlayıcısına (bu örnekte Azure Service Bus) boşaltıyor.

Aşağıdaki tüketicilerden birini oluştururken seçicileri kullanabilirsiniz:

  • Paylaşılan dayanıklı abonelik
  • Paylaşılmayan dayanıklı abonelik
  • Paylaşılan kısa süreli abonelik
  • Paylaşılmayan dayanıklı olmayan abonelik
  • Kuyruk tüketicisi
  • Kuyruk tarayıcısı

Uyarı

Service Bus seçiciler LIKE ve BETWEEN SQL anahtar sözcüklerini desteklemez.

Zamanlanmış iletiler (teslim gecikmesi)

JMS 2.0, bir mesajın gelecekte teslim edilmesi için setDeliveryDelay yöntemini MessageProducer veya JMSProducer üzerinde kullanarak zamanlamayı destekler. Bu özelliği ayarladığınızda, Service Bus iletiyi kabul eder ancak yalnızca gecikme süresi geçtikten sonra tüketicilere görünür hale getirir.

MessageProducer producer = session.createProducer(queue);

// Schedule a message for delivery 30 seconds from now
producer.setDeliveryDelay(30000);
producer.send(session.createTextMessage("Scheduled message"));

Eksiksiz bir çalışma örneği için azure-servicebus-jms-samples deposundaki QueueScheduledSend.java bölümüne bakın.

Bağlantı fabrikası seçimi ve dayanıklılığı

Spring Boot'ta veya JMS bağlantılarını yöneten diğer çerçevelerde kullandığınızda ServiceBusJmsConnectionFactory , güvenilir bir işlem sağlamak için gönderenler ve dinleyiciler için doğru bağlantı fabrikası sarmalayıcısını seçin.

Role Bağlantı fabrikası Neden?
Gönderenler (JmsTemplate) CachingConnectionFactory Kaydırma ServiceBusJmsConnectionFactory JmsTemplate varsayılan olarak gönderme başına bir bağlantı oluşturur ve kapatır. CachingConnectionFactory tek bir AMQP bağlantısı tutar ve oturumları önbelleğe alır ve yük altında aracı kaynaklarını tüketebilecek bağlantı değişim sıklığından kaçınır.
Dinleyiciler (@JmsListener, DefaultMessageListenerContainer) Ham ServiceBusJmsConnectionFactory (açılmamış) Her bir dinleyici kapsayıcısı, bağımsız yaşam döngüsüne sahip kendi AMQP bağlantısını alır. Bağlantı başarısız olursa (token süresi dolması, ağ geçidi yükseltmesi, ağ kesintisi), yalnızca bu dinleyici etkilenir ve Spring Framework bağlantıyı otomatik olarak yeniden oluşturur.

Dinleyiciler için kaçınılması gerekenler

Warning

SingleConnectionFactory dinleyici kapsayıcılarıyla asla kullanmayın. Tüm dinleyicileri tek bir JMS bağlantısını paylaşmaya zorlar. Bu bağlantı herhangi bir nedenle kesilirse, tüm dinleyiciler aynı anda bağlantıyı kaybeder ve bağımsız olarak kurtarılamaz. Her dinleyici kapsayıcısının kendi bağlantısını yönetmesi için ham ServiceBusJmsConnectionFactory öğesini kullanın.

CachingConnectionFactory önbelleğe alınmış oturumlar eski bir temel bağlantıya başvurabileceğinden dinleyici kapsayıcılarında da sorunlara neden olabilir. Dinleyiciler için ham fabrika, her kapsayıcının bağımsız olarak yeni bir bağlantı oluşturabilmesini sağlar.

Spring Cloud Azure varsayılanları

Kullanıyorsanız spring-cloud-azure-starter-servicebus-jms (sürüm 6.2.0+), başlatıcı bu fabrika ayrımını varsayılan olarak uygular:

spring.jms.servicebus.pool.enabled spring.jms.cache.enabled Gönderici fabrikası Dinleyici fabrikası
(ayarlanmadı) (ayarlanmadı) CachingConnectionFactory ServiceBusJmsConnectionFactory
(ayarlanmadı) true CachingConnectionFactory CachingConnectionFactory
(ayarlanmadı) false ServiceBusJmsConnectionFactory ServiceBusJmsConnectionFactory
true (ayarlanmadı) JmsPoolConnectionFactory JmsPoolConnectionFactory

Eski sürümlerde (6.2.0 öncesi) hem gönderenler hem de dinleyiciler varsayılan olarak kullanır ServiceBusJmsConnectionFactory ve bu da gönderenlerin her gönderme için yeni bir bağlantı oluşturmasına neden olur.

Özel durum dinleyicisi ekleme

Özel durum dinleyicisi olmadan bağlantı düşmeleri tamamen sessiz gerçekleşir. Gözlemlenebilirlik sağlamak için, hem gönderici hem de dinleyici fabrikalarına bir jakarta.jms.ExceptionListener ekleyin.

connection.setExceptionListener(exception -> {
    log.error("JMS connection error: {}", exception.getMessage(), exception);
});

Spring Boot'ta özel durum dinleyicisini CachingConnectionFactory (gönderenler için) ve DefaultJmsListenerContainerFactory (dinleyiciler için) ayarlayın.

Bu desenlerin tümünü gösteren eksiksiz bir çalışma örneği için azure-servicebus-jms-samples deposundaki Spring Boot JMS Dayanıklılığı örneğine bakın.

Teslim edilemeyen ileti kuyrukları

Azure Service Bus'daki her kuyruk ve konu aboneliği için ilişkili bir geçersiz mektup kuyruğu (DLQ) vardır. Sistem, teslim edemediği veya işleyemediği iletileri otomatik olarak DLQ'ya taşır. Örneğin, ileti maksimum teslim sayısını aştığında veya yaşam süresi (TTL) dolduğunda sistem bir iletiyi DLQ'ya taşır.

Önemli

TTL süresi dolan iletileri DLQ'ya taşımak için, kuyruk veya abonelik için mesaj süresi dolduğunda ölü-mektup kuyruğu oluşturmayı etkinleştirin. Bu ayar olmadan sistem süresi dolan iletileri sessizce atar. Yapılandırma adımları için bkz kuyruk veya abonelik için geçersiz harf kullanımı etkinleştirme.

JMS'de, tam yolu oluşturarak ve bununla bir JmsQueue yaratarak DLQ'ya ayrı bir hedef olarak erişebilirsiniz. Özel API gerekmez.

Kuyruk DLQ yol biçimi:

<queue-name>/$deadletterqueue

Konu aboneliği DLQ yol biçimi:

<topic-name>/Subscriptions/<subscription-name>/$deadletterqueue

Örnek - bir kuyruğun ölü mektup kuyruğundan tüketim:

import org.apache.qpid.jms.JmsQueue;

// Construct the DLQ path for a queue named "orders"
String dlqPath = "orders/$deadletterqueue";
JmsQueue dlqDestination = new JmsQueue(dlqPath);

// Create a consumer on the DLQ and receive messages
MessageConsumer dlqConsumer = session.createConsumer(dlqDestination);
Message message = dlqConsumer.receive(5000);

Teslim edilemeyen iletiler, iletinin neden teslim edilmediğini açıklayan meta veri özellikleri içerir:

Mülkiyet Description
DeadLetterReason İletinin gönderilmemiş olmasının nedeni (örneğin, TTLExpiredException veya MaxDeliveryCountExceeded).
DeadLetterErrorDescription Ölü harf nedeninin insan tarafından okunabilen bir açıklaması.

Bu özellikleri message.getStringProperty() kullanarak okuyun.

String reason = message.getStringProperty("DeadLetterReason");
String description = message.getStringProperty("DeadLetterErrorDescription");

Eksiksiz bir çalışma örneği için azure-servicebus-jms-samples deposundaki QueueDeadLetterReceive.java bölümüne bakın.

AMQP dağıtımı ve Service Bus işlem eşlemesi

AMQP dağıtımının Service Bus işlemine nasıl çevrildiği şöyledir:

ACCEPTED = 1; -> Complete()
REJECTED = 2; -> DeadLetter()
RELEASED = 3; (just unlock the message in service bus, will then get redelivered)
MODIFIED_FAILED = 4; -> Abandon() which increases delivery count
MODIFIED_FAILED_UNDELIVERABLE = 5; -> Defer()

Özet

Bu geliştirici kılavuzu, Java İleti Hizmeti (JMS) kullanan Java istemci uygulamalarının Azure Service Bus nasıl bağlanabileceğini gösterir.

Sonraki adımlar

Azure Service Bus ve Java İleti Hizmeti (JMS) varlıkları hakkında daha fazla bilgi için aşağıdaki makalelere bakın:

  • Last updated on