JMS-Sender-Adapter konfigurieren
Verwendung
Sie konfigurieren den JMS-Sender-Adapter, um JMS-Nachrichten an die Integration Engine zu verschicken.
Die Konfiguration besteht im Wesentlichen aus der Angabe
● der entsprechenden Java-Klasse
· von allgemeinen Adapter-Einstellungen
· des zu empfangenden Nachrichtentyps
· der Transformationsklasse sowie den 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
...
1. den entsprechenden Adapter installiert
2. den Adapter in der Konfigurationsoberfläche ausgewählt
3. über Konfigurieren die Konfiguration des Adapters aufgerufen
Vorgehensweise
Für den JMS-Sender-Adapter besteht die Konfiguration aus sechs funktionalen Teilbereichen:
...
1. 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.
2. Der Name der Java-Klasse für den JMS-Sender-Adapter
Geben Sie den Namen der Klasse folgendermaßen an:
classname=com.sap.aii.messaging.adapter.ModuleJMS2Transport
Diese Angabe ist zwingend.
3. Allgemeine Adapter-Einstellungen
Folgende allgemeine Parameter können Sie für den JMS-Sender-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.
¡ 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.
Diese Funktionalität setzt voraus, dass Ihr JMS-Provider die Registrierung eines ExceptionListener unterstützt.
4. Der Nachrichtentyp, der zu empfangen bzw. zu senden ist
JMS-seitig kennt der JMS-Adapter folgende Nachrichten:
¡ JMSMessage
¡ JMSTextMessage
¡ JMSBytesMessage
¡ JMSObjectMessage
¡ JMSStreamMessage
¡ JMSMapMessage
Näheres hierzu finden Sie in der Dokumentation zu JMS.
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.
Die Architektur des JMS-Adapters ist so ausgelegt, dass prinzipiell jede JMS-Nachricht auf eine HTTP-Nachricht abgebildet werden kann.
Geben Sie in der Konfiguration an, welcher Nachrichtentyp gesendet werden soll.
¡ TransportMessage.type=TransportMessage oder XMBMessage
Der Vorschlagswert ist XMBMessage.
Der folgende Parameter wird zur Laufzeit gesetzt:
¡ JMSMessage.type
5. 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 unter transformClass die zu verwendende Transformationsklasse 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 Abbildungsvorschriften 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 die Sie als Transformationsklasse eintragen. Als Vorlage können Sie die Klasse JMSTunneling oder JMSSinglePayloadBinding verwenden, deren Funktionalität im folgenden Schritt erläutert wird.
In der Klasse com.sap.aii.messaging.adapter.trans.JMSTunneling ist jeweils ein Binding für folgende Fälle implementiert:
¡ JMSTextMessage àTransportMessage
¡ JMSBytesMessage àTransportMessage
Wie der Klassenname bereits verrät, handelt es sich bei den Bindings jeweils um eine Art JMS-Tunneling, das heißt, die Transport-Message wird in der JMS-Payload transportiert.
In der Klasse com.sap.aii.messaging.adapter.trans.JMSSinglePayloadBinding ist jeweils ein Binding für folgende Fälle implementiert:
¡ JMSTextMessage àTransportMessage
Die Payload einer JMSTextMessage wird als Payload einer TransportMessage verwendet. Der HTTP Content-Type wird aus dem Wert des Parameters XI.ContentType ermittelt (Vorschlagswert: text/plain).
¡ JMSBytesMessage àTransportMessage
Die Payload einer JMSBytesMessage wird als Payload einer TransportMessage verwendet. Der HTTP Content-Type wird aus dem Wert des Parameters XI.ContentType ermittelt (Vorschlagswert: application/octet-stream)
¡ JMSTextMessage àXMBMessage
Die Payload einer JMSTextMessage wird als Payload einer XMBMessage verwendet. Die Header-Daten der XMBMessage werden aus der Konfiguration gebildet, zum Beispiel:
XI.SenderParty=<Sender>
XI.SenderService=ExtAdapterSender
XI.InterfaceNamespace=http://sap.com/xi/xidemo
XI.Interface=ExtAdapterSenderIF
Diese Adress-Argumente für das Sendersystem sind zwingend. Sie dienen der Identifikation der Adapter-Konfiguration beim Routing und Mapping in der Pipeline der Integration Engine. Dort ist auch die Bedeutung der einzelnen Argumente beschrieben.
Optional können Sie mit dem folgenden Parameter auch das Empfängersystem angeben.
XI.ReceiverParty=<Receiver>
XI.ReceiverService=ExtAdapterReceiver
In diesem Fall benötigen Sie keine Empfängerermittlung beim Routing.
¡ JMSBytesMessage àXMBMessage
Die Payload einer JMSBytesMessage wird als Payload einer XMBMessage verwendet. Die Header-Daten der XMBMessage werden aus der Konfiguration gebildet.
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 in Schritt 3 spezifizierten Nachrichtentypen steuern, welches Binding zur Laufzeit verwendet wird.
6. Die Dispatcherklasse und die vom Dispatcher aufzurufenden User-Exits (optional)
Der JMS-Sender-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.
7. Die Adressierung der Integration Engine
Geben Sie die vollständige Adresse (URL) der Integration Engine ein, an die die Message geschickt werden soll:
XI.TargetURL=http://IntegrationEngineHost:port/pipeline-arguments
Diese Angabe ist zwingend.
Die Adresse der Integration Engine kann auch dynamisch aus dem System Landscape Directory (SLD) ermittelt werden. Hierzu wird in der Konfiguration folgender Eintrag hinzugefügt:
XI.SLDConfiguration=SLDaccessor
In diesem Fall wird für das mit XI.SenderService angegebene System die URL des zugehörigen Integration Server im SLD ausgelesen und anstelle des unter XI.TargetURL angegebenen Wertes verwendet. Daher sollte hier folgendes angegeben werden:
XI.TargetURL=<fromSLD>
Damit der Zugriff funktioniert, muss der Dienst SLDaccessor für den Zugriff ins SLD konfiguriert sein, und die entsprechenden Einträge müssen im SLD gepflegt sein.
Ist der Integration Server nicht direkt, sondern über einen HTTP-Proxy-Server zu erreichen, müssen folgende Parameter gesetzt werden:
XI.proxyHost=<proxyHostname>
XI.proxyPort=<proxyPortnumber>
Hierbei ist <proxyHostname> der Host-Name des Proxy und <proxyPortnumber> der Port, auf dem der Proxy HTTP-Requests annimmt (z.B. 8080).
Wurde für die angegebene URL (HTTP-Service) in der Integration Engine eine Authentifizierung spezifiziert, sind die folgenden Angaben zwingend:
¡ XI.User=<user-name>
¡ XI.Password=<password>
Die Angaben müssen mit denen übereinstimmen, die Sie in der Transaktion SICF in der Integration Engine gemacht haben. Falls Sie keine oder eine ungültige Kombination von Benutzer und Passwort angeben, wird jeder Übertragungsversuch in die Integration Engine mit Transport Exception: http-Error 401 – Unauthorized scheitern.
Der Benutzer muss im Integration Server über die Berechtigungen der Gruppe SAP_XI_APPL_SERV_USER verfügen.
Informationen zur Konfiguration der SSL-Authentifizierung mit Zertifikat finden Sie unter: Zertifikatverwaltung, dort unter Adapter Engine als SSL-Client einrichten
Soll bei der Anmeldung ein anderer Mandant bzw. eine andere Sprache als die Default-Werte der Integration Engine verwendet werden, können Sie zusätzlich die folgenden Parameter setzen:
¡ XI.Client=<client-no>
¡ XI.Language=<language-id>
8. Die provider-spezifischen Einstellungen
Näheres zu den provider-spezifischen Einstellungen finden Sie unter Einstellungen für den JMS-Provider.
Beispiel
Im Folgenden finden Sie eine Beispielkonfiguration für den JMS-Sender-Adapter.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# JMS Adapter Configuration
#
# This configuration can be used as a template to configure the
# JMS sender adapter
#
#**************************************************************************
# Set XI message protocol version. This example is designed for XI 3.0
version=30
#**************************************************************************
#
# JMS message receiver class. Uncomment for receiving JMS messages
classname=com.sap.aii.messaging.adapter.ModuleJMS2Transport
#**************************************************************************
#
# set if a transacted JMS session should be used (default: true)
#JMSSession.sessionTransacted=false
#
# 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
#
#**************************************************************************
#
# set the message formats you want to process
# formats are only needed if they cannot be evaluated at runtime
#
# 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
#
# the following parameters are used in bindings that belong to
# SinglePayloadBinding and require XMBHeader information
#
# uncomment and adjust parameters according to your requirements. Please
# note that the Party identifier needs not to be configured in case of A2A
# scenarios.
# XI.SenderParty=Sender
XI.SenderService=ExtAdapterSender
# XI.ReceiverParty=Receiver
XI.ReceiverService=ExtAdapterReceiver
XI.SenderInterfaceNamespace=http://sap.com/xi/xidemo
XI.SenderInterface=ExtAdapterSenderIF
XI.TraceLevel=1
XI.LoggingLevel=1
XI.QualityOfService=EO
XI.QueueId=ABCDEFABCDEF
XI.ContentType=text/xml
#**************************************************************************
#
# URL of Integration Server to send the messages to
XI.TargetURL=http://<host>:<port>/sap/xi/engine?type=entry
XI.User=XIAF
XI.Password=XIPASS
#**************************************************************************
#
# 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 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 the 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.messaging.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.messaging.adapter.XSLTConversion
#namespace1.XSLTService.XSLTConversion.XSLTFileName=Data/DemoConversion.xsl
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++