From ced6bdec5d0e79340d167bd260216e8cb8856f48 Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Mon, 22 Nov 2010 17:52:42 -0500 Subject: [PATCH] INT-1552 doc polishing --- docs/src/reference/docbook/xmpp.xml | 70 +++++++++++++++-------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/docs/src/reference/docbook/xmpp.xml b/docs/src/reference/docbook/xmpp.xml index 927cba5806..36eaf0762b 100644 --- a/docs/src/reference/docbook/xmpp.xml +++ b/docs/src/reference/docbook/xmpp.xml @@ -30,7 +30,7 @@ Spring integration provides support for XMPP via XMPP adapters which support sending and receiving both XMPP chat messages and presence changes from other entries in your roster. As with other adapters, the XMPP adapters come with support for a convenient namespace-based configuration. - To configure XMPP namespace include the following elements into the headers of your XML configuration file: + To configure the XMPP namespace, include the following elements in the headers of your XML configuration file: org.jivesoftware.smack.packet.Message, or of the type - java.lang.String if you set extract-payload value attribute to 'true' + java.lang.String if you set the extract-payload attribute's value to 'true' when configuring an adapter. Configuration support for the XMPP Inbound Message Channel Adapter is provided via the inbound-channel-adapter element. @@ -82,10 +82,12 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp As you can see amongst the usual attributes this adapter also requires a reference to an XMPP Connection. - It is also important to mention that XMPP inbound adapter is an event driven adapter and a LifeCycle object. - When started it will register a PacketListener that will listen for the incoming XMPP Messages. It forwards those messages - to the underlying adapter which will convert them to Spring Integration Messages and send them to the channel. It will - unregister the PacketListener when it is stopped. + It is also important to mention that the XMPP inbound adapter is an event driven adapter + and a Lifecycle implementation. + When started it will register a PacketListener that will listen for incoming XMPP Chat Messages. + It forwards any received messages to the underlying adapter which will convert them to Spring Integration Messages and + send them to the specified channel. It will unregister the PacketListener + when it is stopped. @@ -102,14 +104,14 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp xmpp-connection="testConnection"/>]]> The adapter expects as its input - at a minimum - a payload of type java.lang.String, and a header value - for XmppHeaders.CHAT_TO that specifies to which user the Message should be sent to. To - create a message you might use the following Java code: + for XmppHeaders.CHAT_TO that specifies to which user the Message should be sent. + To create a message you might use the following Java code: xmppOutboundMsg = MessageBuilder.withPayload("Hello, XMPP!" ) .setHeader(XmppHeaders.CHAT_TO, "userhandle") .build();]]> - Another mechanism of setting such header is by using the XMPP enricher support. Here is an example using the enricher. + Another mechanism of setting the header is by using the XMPP header-enricher support. Here is an example. @@ -124,7 +126,7 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp XMPP also supports broadcasting state. You can use this capability to - let people who have you on their roster see your state changes. This happens all the time with your IM clients - you + let people who have you on their roster see your state changes. This happens all the time with your IM clients; you change your away status, and then set an away message, and everybody who has you on their roster sees your icon or username change to reflect this new state, and additionally might see your new "away" message. If you would like to receive notification, or notify others, of state changes, you can use Spring Integration's "presence" adapters. @@ -133,8 +135,8 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
Inbound Presence Message Channel Adapter - Spring Integration provides an Inbound Presence Message Channel Adapter which supports receiving Presence (Roster) - events from other users in the system. To do this, the adapter "logs in" as a user + Spring Integration provides an Inbound Presence Message Channel Adapter which supports receiving Presence + events from other users in the system who happen to be on your Roster. To do this, the adapter "logs in" as a user on your behalf, registers a RosterListener and forwards received Presence update events as Messages to the channel identified by the channel attribute. The payload of the Message will be a org.jivesoftware.smack.packet.Presence object (see http://www.igniterealtime.org/builds/smack/docs/3.1.0/javadoc/org/jivesoftware/smack/packet/Presence.html). @@ -146,8 +148,8 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp xmpp-connection="testConnection" auto-startup="false"/>]]> As you can see amongst the usual attributes this adapter also requires a reference to an XMPP Connection. - It is also important to mention that this adapter is an event driven adapter and a LifeCycle object. - It will register RosterListener when started and will unregister RosterListener + It is also important to mention that this adapter is an event driven adapter and a Lifecycle implementation. + It will register a RosterListener when started and will unregister that RosterListener when stopped.
@@ -156,9 +158,9 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp Outbound Presence Message Channel Adapter - Spring Integration also supports sending Presence (Roster) events to be seen by other users in the network. When you send a Message - to the Outbound Presence Message Channel Adapter it extracts the payload which is expected to be of - type org.jivesoftware.smack.packet.Presence + Spring Integration also supports sending Presence events to be seen by other users in the network who happen to have you on their + Roster. When you send a Message to the Outbound Presence Message Channel Adapter it extracts the payload, + which is expected to be of type org.jivesoftware.smack.packet.Presence (see http://www.igniterealtime.org/builds/smack/docs/3.1.0/javadoc/org/jivesoftware/smack/packet/Presence.html) and sends it to the XMPP Connection, thus advertising your presence events to the rest of the network. @@ -169,7 +171,7 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp ]]> - It can also be a polling consumer (if it receives Messages from the Polling Channel) in which case you would + It can also be a Polling Consumer (if it receives Messages from a Pollable Channel) in which case you would need to register a Poller. ]]> - Similar to its Inbound counterpart it requires a reference to an XMPP Connection. + Like its inbound counterpart, it requires a reference to an XMPP Connection. @@ -186,17 +188,17 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp Appendices - Since Spring Integration XMPP support is based on Smack 3.1 API (http://www.igniterealtime.org/downloads/index.jsp), it is important - to know a few details related to more complex configuration of XMPP Connection object. + Since Spring Integration XMPP support is based on the Smack 3.1 API (http://www.igniterealtime.org/downloads/index.jsp), it is important + to know a few details related to more complex configuration of the XMPP Connection object. As stated earlier the xmpp-connection namespace support is designed to simplify basic connection configuration and only supports a few common configuration attributes. However, the org.jivesoftware.smack.ConnectionConfiguration - object defines about 20 - attributes, and there is no real value of adding namespace support for all of them. So, for more complex connection configurations, - simply configure XmppConnectionFactoryBean as a regular bean injecting - org.jivesoftware.smack.ConnectionConfiguration as a constructor argument and configuring every property - you may need. This way SSL or any other attributes could be set directly in a consistent Spring way. Example: + object defines about 20 attributes, and there is no real value of adding namespace support for all of them. So, for more complex connection + configurations, simply configure an instance of our XmppConnectionFactoryBean as a regular bean, and inject a + org.jivesoftware.smack.ConnectionConfiguration as a constructor argument to that FactoryBean. Every property + you need, can be specified directly on that ConnectionConfiguration instance (a bean definition with the 'p' namespace would work well). + This way SSL, or any other attributes, could be set directly. Here's an example: @@ -214,26 +216,26 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp xmpp-connection="xmppConnection"/>]]> - Another important aspect of Smack API is static initializers. For more complex cases (e.g., registering SASL Mechanism) you may need - to execute certain static initializers. One of those static initializers is SASLAuthentication which allows - you to register supported SASL mechanisms. For that level of complexity we would recommend Spring JavaConfig-style of XMPP Connection - configuration where you can configure the entire component through Java code and execute all other necessary Java code including - static initializers. + Another important aspect of the Smack API is static initializers. For more complex cases (e.g., registering a SASL Mechanism), you may need + to execute certain static initializers. One of those static initializers is SASLAuthentication, which allows + you to register supported SASL mechanisms. For that level of complexity, we would recommend Spring JavaConfig-style of the XMPP Connection + configuration. Then, you can configure the entire component through Java code and execute all other necessary Java code including + static initializers at the appropriate time. - For more information on the JavaConfig style of Application Context configuration refer to the following section in Spring Reference Manual + For more information on the JavaConfig style of Application Context configuration, refer to the following section in the Spring Reference Manual: http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-java