.. _jms-source-connector: JMS Source Connector for |cp| ============================= The |kconnect-long| JMS Source Connector is used to move messages from any JMS-compliant broker into |ak-tm|. It supports any traditional JMS Broker, such as `IBM MQ `_ , `ActiveMQ `_ , `TIBCO EMS `_ , and `Solace Appliance `_ . This connector uses JNDI to connect to the JMS broker, consume messages from the specified topic or queue, and write them into the specified |ak| topic. .. note:: * :ref:`IBM MQ `, :ref:`ActiveMQ `, and :ref:`TIBCO Source Connector ` Source Connectors are also available. * The IBM MQ and ActiveMQ connectors are included in |cp|. * These are specializations of the JMS Source Connector that avoid JNDI and instead use system-specific APIs to establish connections. These are often easier to configure and use in most situations. Install the JMS Source Connector -------------------------------- .. include:: ../includes/connector-native-install-cpe.rst .. include:: ../includes/connector-install-hub.rst .. codewithvars:: bash confluent-hub install confluentinc/kafka-connect-jms:latest .. include:: ../includes/connector-install-version.rst .. codewithvars:: bash confluent-hub install confluentinc/kafka-connect-jms:|release| -------------------------- Install Connector Manually -------------------------- `Download and extract the ZIP file `_ for your connector and then follow the manual connector installation :ref:`instructions `. .. _jms-source-connector-license-key: License ------- .. include:: ../includes/enterprise-license.rst See :ref:`jms-source-connector-license-config` for license properties and :ref:`jms-source-license-topic-configuration` for information about the license topic. .. _jms-source-connector-client-libs: Client Libraries ---------------- The |kconnect-long| JMS connector works with any JMS-compliant system, but it does not come with client libraries. Instead, you **must** download the JMS client library JARs for your system and add them into the ``share/java/kafka-connect-jms`` directory in *each* of the |cp| installations. If you plan to use multiple JMS source connectors to *different* types of JMS systems, all of the client libraries for those systems should be installed into the same location. However, make sure the libraries don't clash with each other. .. include:: ../includes/classpath-v-pluginpath.rst .. _jms-source-connector-messagetypes: JMS Message types ----------------- The connector currently supports only `TextMessage `_ and `BytesMessage `_ but does not currently support `ObjectMessage `_ or `StreamMessage `_ . .. _jms-source-jndi-connection-factory: JNDI Connection Factory ----------------------- This connector uses `JNDI `_ to create an instance of the JMS `ConnectionFactory `_ for your messaging system. Because of this you must ensure that the relevant client jars for your messaging system are in the classpath along side this connector. .. _jms-source-tibcoems-example: -------------------- Using with TIBCO EMS -------------------- .. note:: A :ref:`TIBCO Source Connector ` is available for installation from |c-hub|. This is a specialization of this connector that avoids JNDI and instead uses system-specific APIs to establish connections. This is often easier to configure and use in most situations. This connector can be used with TIBCO EMS and its support for JMS. First, install the latest TIBCO EMS JMS client libraries into the same directory where this connector is installed. Check the TIBCO EMS installation or documentation for more details. Then, create a connector configuration for your environment, using the appropriate configuration properties. The following example shows a typical configuration of the connector for use with :ref:`distributed mode `. .. codewithvars:: bash { "name": "connector1", "config": { "connector.class": "io.confluent.connect.jms.JmsSourceConnector", "kafka.topic":"MyKafkaTopicName", "jms.destination.name":"MyQueueName", "jms.destination.type":"queue", "java.naming.factory.initial":"com.tibco.tibjms.naming.TibjmsInitialContextFactory", "java.naming.provider.url":"tibjmsnaming://:" "confluent.license":"" "confluent.topic.bootstrap.servers":"localhost:9092" "confluent.topic.ssl.truststore.location"="omitted" "confluent.topic.ssl.truststore.password"="" "confluent.topic.ssl.keystore.location"="omitted" "confluent.topic.ssl.keystore.password"="" "confluent.topic.ssl.key.password"="" "confluent.topic.security.protocol"="SSL" } } .. note:: Any extra properties defined on the connector will be passed into the JNDI InitialContext. This makes it easy to use any TIBCO EMS specific settings. Finally, deploy your connector by posting it to a |kconnect-long| distributed worker. .. _jms-source-ibmmq-example: -------------------------- Using with IBM MQ via LDAP -------------------------- The Confluent Platform includes a custom connector for :ref:`IBM MQ ` that is very easy to configure, and where possible you should use that connector instead of this general JMS connector. However, you may want to use this more general connector if you are required to connect to IBM MQ via LDAP or other JNDI mechanism. First, install the latest IBM MQ JMS client libraries into the same directory where this connector is installed. Check your IBM installation or documentation for more details. Then, create a connector configuration for your environment, using the appropriate configuration properties. The following example shows a typical but incomplete configuration of the connector for use with :ref:`distributed mode `. .. codewithvars:: bash { "name": "connector1", "config": { "connector.class": "io.confluent.connect.jms.JmsSourceConnector", "kafka.topic":"MyKafkaTopicName", "jms.destination.name":"MyQueueName", "jms.destination.type":"queue", "java.naming.factory.initial":"com.sun.jndi.ldap.LdapCtxFactory", "java.naming.provider.url":"ldap://" "java.naming.security.principal":"MyUserName", "java.naming.security.credentials":"MyPassword", "confluent.license":"" "confluent.topic.bootstrap.servers":"localhost:9092" } } .. note:: Any extra properties defined on the connector will be passed into the JNDI InitialContext. This makes it easy to pass any IBM MQ specific settings used for connecting to the IBM MQ broker. Finally, deploy your connector by posting it to a |kconnect-long| distributed worker. .. _jms-source-connector-topics: Topics ------ This connector consumes messages from the JMS broker using the configured :ref:`message selectors ` and writes them to a single |ak| topic. If you want to write messages to multiple topics, use a simple message transform that routes the messages based upon your criteria. .. _jms-source-connector-acknowledgement-mode: Acknowledgement Mode -------------------- The connector internally uses ``CLIENT_ACKNOWLEDGE`` mode to receive and acknowledge messages from the JMS broker. In this mode, acknowledging any message will acknowledge every message received (see section 6.2.10 in the `JMS Spec `_). To prevent messages from being prematurely acknowledged, the connector processes only one message at time. In other words, the connector will *not* attempt to receive new messages until the last message is committed to a |ak| topic. This might compromise the throughput of the Connector, but messages will be transferred to |ak| successfully. .. include:: ../includes/jms-message-schemas.rst Additional documentation ------------------------ .. toctree:: :maxdepth: 1 source_connector_config examples changelog