JMS-Empfänger-Adapter konfigurieren

Verwendung

Sie konfigurieren den JMS-Empfänger-Adapter, um XML-Messages von der Integration Engine in JMS-Nachrichten zu verwandeln.

Die Konfiguration besteht im Wesentlichen aus der Angabe

der entsprechenden Java-Klasse
von allgemeinen Adapter-Einstellungen
des zu empfangenden Nachrichtentyps
der Transformationsklasse sowie der in der Transformationsklasse implementierten Abbildungsvorschriften
der Dispatcherklasse (optional) mit den entsprechenden Einstellungen sowie der vom Dispatcher aufzurufenden User-Exits und deren Einstellungen
der Adressierung der Integration Engine
von Einstellungen, die spezifisch für den jeweiligen JMS-Provider sind

Voraussetzungen

Sie haben

den entsprechenden Adapter installiert
den Adapter in der Konfigurationsoberfläche ausgewählt
über Konfigurieren die Konfiguration des Adapter-Moduls aufgerufen

Vorgehensweise

Für den JMS-Empfänger-Adapter besteht die Konfiguration aus sechs funktionalen Teilbereichen:

Die Versionsangabe für die Konfiguration.
version=
```
30
```
Diese Angabe ist zwingend. Fehlt die Angabe, wird die Konfiguration als XI 2.0 Adapter-Konfiguration interpretiert. Andere Werte sind nicht zulässig und werden als Fehler ausgegeben.
Der Name der Java-Klasse für den JMS-Empfänger-Adapter
Geben Sie den Namen der Klasse folgendermaßen an:
classname=
```
com.sap.aii.messaging.adapter.ModuleTransport2JMS
```
Diese Angabe ist zwingend.
Allgemeine Adapter-Einstellungen
Folgende allgemeine Parameter können Sie für den JMS-Empfänger-Adapter einstellen:
- JMSSession.sessionTransacted=true oder false
  Der Vorschlagswert ist true
  
  Dieser Parameter steuert, ob eine transaktionale JMS-Session verwendet werden soll oder nicht. Eine transaktionale Session wird nach der Verarbeitung einer Nachricht entweder mit COMMIT abgeschlossen oder im Fehlerfall mit ROLLBACK zurückgesetzt.
- JMS.MessageProducer.DeliveryMode= PERSISTENTNON_PERSISTENT oder Der Vorschlagswert ist PERSISTENT . Dieser Parameter steuert den Zustellungsmodus der zu versendenden JMS-Nachrichten.
- errorDelay Der Vorschlagswert für diesen Parameter ist 0 . Der Parameter steuert, wie lange bei einem Verarbeitungsfehler gewartet wird, bis weitere Nachrichten verarbeitet werden. Eine gewisse Wartezeit kann beispielsweise bei transaktionaler Verarbeitung sinnvoll sein, da fehlerhafte Nachrichten nach einem ROLLBACK in der Warteschlange stehen bleiben.
- reconnectDelay
  Der Vorschlagswert für diesen Parameter ist -1.
  
  Der Parameter steuert, ob und in welchem Zeitintervall bei einem JMS-seitigen Verbindungsfehler versucht werden soll, die Verbindung neu aufzubauen. Das Zeitintervall wird in Millisekunden angegeben. Bei einem Wert von -1 wird nicht versucht die Verbindung neu aufzubauen.
  
  Hinweis
  Diese Funktionalität setzt voraus, dass Ihr JMS-Provider die Registrierung eines ExceptionListener unterstützt.
- forceReconnectString=<string>
  Der Parameter bietet die Möglichkeit einen Neuaufbau der Verbindung selektiv zu erzwingen, falls der JMS-Provider bei Verbindungsfehlern im Ausgangsfall nicht den vom JMS-Adapter registrierten ExceptionListener aufruft.
  
  Falls beim Verschicken einer Message eine JMSException ausgelöst wird, wird der darin enthaltende (provider-spezifische) Freitext mit dem angegeben String verglichen und gegebenenfalls der Versuch unternommen, in Abhängigkeit vom Wert des Parameters reconnectDelay die Verbindung wieder aufzubauen.
Der Nachrichtentyp, der zu empfangen bzw. zu senden ist
HTTP-seitig kennt der JMS-Adapter die Nachrichten
- TransportMessage
  Ist im wesentlichen eine (single oder multipart) MIME-Message mit einer Bindung an das Transportprotokoll (HTTP). Sie dient dem Transport einer XMBMessage.
- XMBMessage
  Ist eine von SAP definierte SOAP-Nachricht mit Attachments, die logisch auf einer Multipart-MIME-Message basiert.
JMS-seitig kennt der JMS-Adapter folgende Nachrichten:
- JMSMessage
- JMSTextMessage
- JMSBytesMessage
- JMSObjectMessage
- JMSStreamMessage
- JMSMapMessage
Näheres hierzu finden Sie in derDokumentation zu JMS .

Die Architektur des JMS-Adapters ist so ausgelegt, dass prinzipiell jede HTTP-Nachricht auf eine JMS-Nachricht abgebildet werden kann.

Geben Sie in der Konfiguration an, welcher Nachrichtentyp zu empfangen ist:
- TransportMessage.type=
```
TransportMessageXMBMessage
```
  oder
  Der Vorschlagswert ist
```
XMBMessage
```
Geben Sie weiterhin an, welcher JMS-Message-Typ gesendet werden soll:
- JMSMessage.type=
```
TextMessageBytesMessage
```
  oder
  Der Vorschlagswert ist
```
JMSTextMessage
```
Die Transformationsklasse, in der die Abbildungsvorschriften (Bindings) zur Umsetzung unterschiedlicher Nachrichtenformate implementiert sind, sowie die Festlegung der konkreten Abbildungen für die Nachrichtenformate
Geben Sie in der Konfiguration die zu verwendende Transformationsklasse unter transformClass an. Mit ausgeliefert werden die Klassen
- com.sap.aii.messaging.adapter.trans.JMSTunneling
- com.sap.aii.messaging.adapter.trans.JMSSinglePayloadBinding
Sie können jederzeit eigene Abbildungsvorschrift definieren und in den JMS-Adapter einbinden, indem Sie eine eigene Klasse implementieren, die die Klasse com.sap.aii.messaging.adapter.trans.Transform erweitert, und sie als Transformationsklasse eintragen. Als Vorlage können Sie die Klasse JMSTunneling oder JMSSinglePayloadBinding verwenden, deren Funktionalität im Folgenden kurz erläutert wird.

In der Klasse com.sap.aii.messaging.adapter.trans.JMSTunneling ist jeweils ein Binding für folgende Fälle implementiert:
- TransportMessage → JMSTextMessage
- TransportMessage → JMSBytesMessage
- XMBMessage → JMSTextMessage
- XMBMessage → JMSBytesMessage
Wie der Klassenname bereits verrät, handelt es sich bei den Bindings jeweils um eine Art JMS-Tunneling, das heißt, die TransportMessage bzw. XMBMessage wird in der JMS-Payload transportiert.

Es sind keine weiteren Konfigurationsparameter notwendig. Die in Schritt 3 spezifizierten Nachrichtentypen steuern, welches Binding zur Laufzeit verwendet wird.

In der Klasse com.sap.aii.messaging.adapter.trans.JMSSinglePayloadBinding ist jeweils ein Binding für folgende Fälle implementiert:
- TransportMessage → JMSTextMessage
  Die Payload einer TransportMessage wird als Payload einer JMSTextMessage verwendet. Zur Bestimmung, ob die Payload der TransportMessage textartig ist, dient der Wert in dem HTTP Header-Feld
  content-Type (=
```
text/...
```
  )
- TransportMessage → JMSBytesMessage
  Die Payload einer TransportMessage wird als Payload einer JMSBytesMessage verwendet. Zur Bestimmung, ob die Payload der TransportMessage nicht textartig ist, dient der Wert in dem HTTP Header-Feld
  content-Type ( <>
```
text/...
```
  )
- XMBMessage → JMSTextMessage
  Die Payload einer XMBMessage wird als Payload einer JMSTextMessage verwendet. Zur Bestimmung, ob die Payload der XMBMessage textartig ist, wird der Payload-Typ herangezogen. Die Header-Daten der XMBMessage werden ignoriert.
- XMBMessage → JMSBytesMessage
  Die Payload einer XMBMessage wird als Payload einer JMSBytesMessage verwendet. Zur Bestimmung, ob die Payload der XMBMessage nicht textartig ist, wird der Payload-Typ herangezogen. Die Header-Daten der XMBMessage werden ignoriert.
Während JMS von den Bindings in der Klasse JMSTunneling quasi als Transportmittel benutzt wird, sind die Bindings in der Klasse JMSSinglePayloadBinding sehr viel spezieller.
Die Dispatcherklasse und die vom Dispatcher aufzurufenden User-Exits (optional)
Der JMS-Empfänger-Adapter bietet einen Dispatcher an, mit dem Sie Messages vor dem Verschicken konvertieren können. Die für den Dispatcher notwendigen Einstellungen werden anhand eines konkreten Beispiels erklärt.
Die Angaben für die Adressierung der Integration Engine
- XI.httpPort=
```
<port_no>
```
```
<port_no>
```
  gibt den Port des HTTP-Servers an, der die Nachrichten der Integration Engine entgegennimmt.
- XI.httpService=
```
<service>
```
  <service> beschreibt den Service-Teil der Adresse, zu dem die Integration Engine ihre Nachrichten schicken muss.
Diese Angaben sind zwingend.
Hinweis
Haben Sie zum Beispiel
```
XI.httpPort=1234XI.httpService=/JMS
```
und spezifiziert, muss die Endpunkt-Adresse des JMS-Adapters in der Integration Engine wie folgt spezifiziert sein:
```
http://<JMSAdapterhost>:1234/JMS
```
Achtung
Für die Integration Engine in der Version 1.0 muss die Endpunkt-Adresse wie folgt erweitert werden:
```
http://<JMSAdapterhost>:1234/JMS?action=execute&pipelineid=Receiver
```
Wird die Nachricht von der Integration Engine an einen nicht spezifizierten Service des Adapters geschickt, erfolgt die Fehlermeldung

No registered listener for <service> found
Die gleiche Fehlermeldung erhält man, wenn der Adapter initialisiert, aber nicht gestartet ist (sich also im Status
```
ANGEHALTENINITIALISIERT
```
oder befindet).
Die provider-spezifischen Einstellungen
Näheres zu den provider-spezifischen Einstellungen finden Sie unter Einstellungen für den JMS-Provider .
Der Adapter kann ein synchrones System-Acknowledgment zurücksenden, wenn es vom Sender angefordert wird. Das Acknowledgment bestätigt, dass die Nachricht an den Empfänger ausgeliefert wurde.
- Wollen Sie ein synchrones System-Acknowledgment zurücksenden, setzten Sie XI.AckFinal=true . Dies ist der Vorgabewert.
- Wollen Sie vermeiden, dass ein synchrones System-Acknowledgment zurückgesendet wird, auch wenn es vom Sender angefordert wird, setzen Sie XI.AckFinal=false .

Beispiel

Im Folgenden finden Sie eine Beispielkonfiguration für den JMS-Empfänger-Adapter.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

# JMS Adapter Configuration

# This configuration can be used as a template to configure the

# JMS receiver adapter

#**************************************************************************

# Set XI message protocol version. This example is designed for XI 3.0

version=30

#**************************************************************************

# JMS message sender class Uncomment for sending JMS messages

classname=com.sap.aii.messaging.adapter.ModuleTransport2JMS

#**************************************************************************

# set if a transacted JMS Session should be used (default: true)

#JMSSession.sessionTransacted=false

# set the delivery mode of the JMS MessageProducer (QueueSender, default: PERSISTENT)

#JMS.MessageProducer.DeliveryMode=NON_PERSISTENT

# set delay in milliseconds before processing next message after an error

# (default: 0)

#errorDelay=10000

#

# set delay in milliseconds before trying to reestablish the JMS connection

# after a connection error (default: -1 (do not try to reconnect))

#reconnectDelay=10000

#

# force reconnect (only to be used if the JMS Provider does not support the

# JMSExceptionListener functionality) the reconnect is only attempted if

# the JMSException message contains the forceReconnectString or if the

# forceReconnectString is set to * (default: forceReconnectString is not

# set -> no reconnect is attempted

#forceReconnectString=MQJMS2007

#**************************************************************************

# set the message formats you want to process

# formats are only needed if they cannot be evaluated at runtime

# JMSMessage Type can be set to TextMessage or BytesMessage

# it is only used for sending JMS messages

#JMSMessage.type=BytesMessage

JMSMessage.type=TextMessage

# TransportMessage Type can be set to TransportMessage or XMBMessage

# it is used for sending and receiving TransportMessages and XMBMessages

#TransportMessage.type=TransportMessage

TransportMessage.type=XMBMessage

#**************************************************************************

# uncomment and adjust parameters for Transformation Type

# (binding of JMS TransportMessage); insert your class here for an

# individual binding between JMS and TransportMessage

# uncomment the following line for using bindings that belong to Tunneling

#transformClass=com.sap.aii.messaging.adapter.trans.JMSTunneling

# uncomment the following line for using bindings that belong to

# SinglePayloadBinding

transformClass=com.sap.aii.messaging.adapter.trans.JMSSinglePayloadBinding

#**************************************************************************

# uncomment and adjust parameters for the HTTP listener ports to wait for

# XI messages

XI.httpPort=3333

XI.httpService=/JMS

#**************************************************************************

# uncomment and adjust parameters for loading JMS administrated objects via

# JNDI

# uncomment and adjust parameters if not the default context should be used

#JNDI.InitialContext.property.1=java.lang.String

#{javax.naming.Context.INITIAL_CONTEXT_FACTORY}, java.lang.String

#com.sap.engine.services.jndi.InitialContextFactoryImpl

#JNDI.InitialContext.property.2=java.lang.String

#{javax.naming.Context.PROVIDER_URL}, java.lang.String localhost:50004

#JNDI.InitialContext.property.3=java.lang.String

#{javax.naming.Context.SECURITY_PRINCIPAL}, java.lang.String Administrator

#JNDI.InitialContext.property.4=java.lang.String

#{javax.naming.Context.SECURITY_CREDENTIALS}, java.lang.String sap

# set the Lookup Names

#JMS.JNDILookupNameQueueConnectionFactory=jmsfactory/default/joetest

#JMS.JNDILookupNameQueue=jmsQueues/default/sapDemoQueue

#**************************************************************************

# uncomment and adjust parameters for loading JMS administrated objects

# from the file system

#JMS.FileNameQueueConnectionFactory=SAPQueueConnectionFactory.ser

#JMS.FileNameQueue=SAPQueue.ser

#**************************************************************************

# uncomment and adjust parameters for creating SonicMQ

# JMS administrated objects

JMS.QueueConnectionFactoryImpl.classname=progress.message.jclient.QueueConnectionFactory

JMS.QueueConnectionFactoryImpl.constructor=java.lang.String p49512:2506

JMS.QueueImpl.classname= progress.message.jclient.Queue

JMS.QueueImpl.constructor=java.lang.String SampleQ1

#**************************************************************************

# uncomment and adjust parameters for creating WebSphereMQ

# JMS administrated objects

#JMS.QueueConnectionFactoryImpl.classname=com.ibm.mq.jms.MQQueueConnectionFactory

#JMS.QueueConnectionFactoryImpl.method.setHostName=java.lang.String p24537

#JMS.QueueConnectionFactoryImpl.method.setChannel=java.lang.String JAVA.CHANNEL

#JMS.QueueConnectionFactoryImpl.method.setTransportType=java.lang.Integer {com.ibm.mq.jms.JMSC.MQJMS_TP_CLIENT_MQ_TCPIP}

#JMS.QueueConnectionFactoryImpl.method.setQueueManager=java.lang.String QM_p24537

#JMS.QueueImpl.classname= com.ibm.mq.jms.MQQueue

#JMS.QueueImpl.constructor=java.lang.String postcard

#JMS.QueueImpl.method.setTargetClient=java.lang.Integer {com.ibm.mq.jms.JMSC.MQJMS_CLIENT_NONJMS_MQ}

#**************************************************************************

# uncomment and adjust parameters for using a dispatcher ***

#Dispatcher.class=com.sap.aii.messaging.adapter.ConversionDispatcher

#Dispatcher.namespace=namespace1

#namespace1.ConversionDispatcher.logPayload=true

#namespace1.Service.1=Plain2XMLService

#namespace1.Plain2XMLService.class=com.sap.aii.af.sdk.xi.adapter.Conversion

#namespace1.Plain2XMLService.xml.conversionType=SimplePlain2XML

#namespace1.Plain2XMLService.xml.processFieldNames=fromConfiguration

#namespace1.Plain2XMLService.xml.fieldNames=a,b,c

#namespace1.Plain2XMLService.xml.fieldSeparator=;

#namespace1.Service.2=XSLTService

#namespace1.XSLTService.class=com.sap.aii.af.sdk.xi.adapter.XSLTConversion

#namespace1.XSLTService.XSLTConversion.XSLTFileName=Data/DemoConversion.xsl

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++