.. _client_jms: |cjms| ====== Java Message Service (JMS) is a widely used messaging API that is included as part of the Java Platform, Enterprise Edition. |cjms-full| (``kafka-jms-client``) is an implementation of the `JMS 1.1 provider interface `_ that allows |ak-tm| or |cp| to be used as a JMS message broker. ``[kafka-jms-client] <--- kafka protocol ---> [kafka broker]`` Applications written using Confluent's `kafka-jms-client` can exchange messages with other application written using `kafka-jms-client` as well as any application that produces or consumes messages using any other |ak| client library. The purpose of this client is to allow existing applications written to the JMS API to be able to publish and subscribe to |ak| as a replacement for any other JMS broker. If you are interested in integrating |ak| with an existing JMS broker (i.e. without replacing it) then you are encouraged to look at the :ref:`Kafka Connect API ` or any pre-built |ak| Source or Sink Connectors for JMS. If you are interested in writing new Java applications then you are encouraged to use the Java |ak| Producer/Consumer APIs as they provide advanced features not available when using the `kafka-jms-client`. JMS 1.1 Compatibility --------------------- Where possible, the |ak| |cjms| is a complete implementation of the JMS 1.1 specification. However there are some JMS concepts that either do not map 1:1 to |ak|, or simply do not make sense at all in |ak| (such as nonpersistent messages). JMS brokers typically provide distinct `Topic `_ and `Queue `_ functionality that reflects that in the JMS Specification. By contrast, |ak| provides only one abstraction - partitioned topics - which are actually distributed commit logs and behave differently to the traditional messaging system notion of a topic. In practice, |ak| topics can mimic the behavior of either topics or queues in the traditional messaging system sense. Additional notes on JMS 1.1 compatibility are outlined below. Features ^^^^^^^^ Both JMS messaging models are supported: * Publish/Subscribe (Topics) * Point-to-Point (Queues) All JMS message types are supported including: * ``TextMessage`` * ``BytesMessage`` * ``MapMessage`` * ``StreamMessage`` * ``ObjectMessage`` Treatment of JMS header values: * ``JMSDestination`` - Set (overwritten) to on send and available in message at the destination. * ``JMSDeliveryMode`` - Set (overwritten) to DEAULT_DELIVERY_MODE (PERSISTED) on send. * ``JMSExpiration`` - Ignored. Overwritten with 0 on send. * ``JMSPriority`` - Ignored. Set (overwritten) with DEFAULT_PRIORITY (4) on send. * ``JMSMessageID`` - Set (overwritten) with a unique id for the message on send and available in message at destination. * ``JMSTimestamp`` - Set (overwritten) on message send and transmitted to destination if this has not been disabled using ``MessageProducer.setDisableMessageTimestamp``. * ``JMSCorrelationID`` - Value set by user is transmitted to destination. * ``JMSReplyTo`` - Value set by user is transmitted to destination. * ``JMSType`` - Value set by user is transmitted to destination. * ``JMSRedelivered`` - Ignored. Set (overwritten) to false on send. Only durable topics/queues are supported. Unsupported Features ^^^^^^^^^^^^^^^^^^^^ The following functionality has either limited support or no support: Session ~~~~~~~ ======================================================= ======================================================================================= Method Notes ======================================================= ======================================================================================= createDurableSubscriber(Topic, String) Durable Subscribers are not supported. createDurableSubscriber(Topic, String, String, boolean) Durable Subscribers are not supported. getMessageListener() Session based MessageListeners are not supported. setMessageListener(MessageListener) Session based MessageListeners are not supported. rollback() Transactions are not supported by |ak|. recover() Transactions are not supported by |ak| commit() Transactions are not supported by |ak|. createBrowser(Queue, String) QueueBrowsers with message selectors are not supported. unsubscribe(String) Durable Subscribers are not supported. createConsumer(Destination, String) Message selectors are not supported. An exception will be thrown if one is set. createConsumer(Destination, String, boolean) Message selectors are not supported. An exception will be thrown if one is set. createTemporaryTopic() |ak| does not have a concept of a temporary topic. getTransacted() Transactions are not supported. This will always return false. createTemporaryQueue() |ak| does not have a concept of a temporary topic. ======================================================= ======================================================================================= ConnectionFactory ~~~~~~~~~~~~~~~~~ ================================= ========================================================================================================= Method Notes ================================= ========================================================================================================= createConnection(String, String) Not supported. Authentication is only supported via |ak| configuration properties. ================================= ========================================================================================================= Connection ~~~~~~~~~~ ======================================= ================================================================================================================ Method Notes ======================================= ================================================================================================================ setClientID(String) Setting the client id is only supported by using `client.id` in the settings passed to KafkaConnectionFactory. ======================================= ================================================================================================================ .. toctree:: :hidden: :maxdepth: 1 installation dev-guide