Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

INT-1552 doc polishing

Browse Source
This commit is contained in:
Mark Fisher
2010-11-22 17:52:42 -05:00
parent a5b8643e3b
commit ced6bdec5d
1 changed files with 36 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/src/reference/docbook/xmpp.xml
View File

@@ -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:
<programlisting language="xml"><![CDATA[xmlns:xmpp="http://www.springframework.org/schema/integration/xmpp"
xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
@@ -69,7 +69,7 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
forwarded to your Spring Integration client.
The payload of the inbound Spring Integration message may be of the raw type<classname>
org.jivesoftware.smack.packet.Message</classname>, or of the type
<classname>java.lang.String</classname> if you set <code>extract-payload</code> value attribute to 'true'
<classname>java.lang.String</classname> if you set the <code>extract-payload</code> attribute's value to 'true'
when configuring an adapter.
Configuration support for the XMPP <emphasis>Inbound Message Channel Adapter</emphasis> is provided via the <code>inbound-channel-adapter</code> 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.
</para>
<para>
It is also important to mention that XMPP inbound adapter is an <emphasis>event driven adapter</emphasis> and a <classname>LifeCycle</classname> object.
When started it will register a <classname>PacketListener</classname> 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 <classname>channel</classname>. It will
unregister the <classname>PacketListener</classname> when it is stopped.
It is also important to mention that the XMPP inbound adapter is an <emphasis>event driven adapter</emphasis>
and a <classname>Lifecycle</classname> implementation.
When started it will register a <classname>PacketListener</classname> 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 <classname>channel</classname>. It will unregister the <classname>PacketListener</classname>
when it is stopped.
</para>
</section>
@@ -102,14 +104,14 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
xmpp-connection="testConnection"/>]]></programlisting>
The adapter expects as its input - at a minimum - a payload of type <classname>java.lang.String</classname>, and a header value
for <classname>XmppHeaders.CHAT_TO</classname> that specifies to which user the Message should be sent to. To
create a message you might use the following Java code:
for <classname>XmppHeaders.CHAT_TO</classname> that specifies to which user the Message should be sent.
To create a message you might use the following Java code:
<programlisting language="java"><![CDATA[Message<String> xmppOutboundMsg = MessageBuilder.withPayload("Hello, XMPP!" )
.setHeader(XmppHeaders.CHAT_TO, "userhandle")
.build();]]></programlisting>
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.
<programlisting language="xml"><![CDATA[<int-xmpp:header-enricher input-channel="input" output-channel="output">
<int-xmpp:chat-to value="test1@example.org"/>
@@ -124,7 +126,7 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
<para>
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
<section id="xmpp-roster-inbound-channel-adapter">
<title>Inbound Presence Message Channel Adapter</title>
<para>
Spring Integration provides an <emphasis>Inbound Presence Message Channel Adapter</emphasis> 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 <emphasis>Inbound Presence Message Channel Adapter</emphasis> 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 <classname>RosterListener</classname> and forwards received Presence update events as Messages to the channel
identified by the <code>channel</code> attribute. The payload of the Message will be a <classname>org.jivesoftware.smack.packet.Presence</classname>
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"/>]]></programlisting>
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 <classname>LifeCycle</classname> object.
It will register <classname>RosterListener</classname> when started and will unregister <classname>RosterListener</classname>
It is also important to mention that this adapter is an event driven adapter and a <classname>Lifecycle</classname> implementation.
It will register a <classname>RosterListener</classname> when started and will unregister that <classname>RosterListener</classname>
when stopped.
</para>
</section>
@@ -156,9 +158,9 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
<title>Outbound Presence Message Channel Adapter</title>
<para>
Spring Integration also supports sending Presence (Roster) events to be seen by other users in the network. When you send a Message
to the <emphasis>Outbound Presence Message Channel Adapter</emphasis> it extracts the payload which is expected to be of
type <classname>org.jivesoftware.smack.packet.Presence</classname>
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 <emphasis>Outbound Presence Message Channel Adapter</emphasis> it extracts the payload,
which is expected to be of type <classname>org.jivesoftware.smack.packet.Presence</classname>
(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.
</para>
@@ -169,7 +171,7 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
<programlisting language="xml"><![CDATA[<int-xmpp:presence-outbound-channel-adapter id="eventOutboundPresenceChannel"
xmpp-connection="testConnection"/>]]></programlisting>
It can also be a <emphasis>polling consumer</emphasis> (if it receives Messages from the Polling Channel) in which case you would
It can also be a <emphasis>Polling Consumer</emphasis> (if it receives Messages from a Pollable Channel) in which case you would
need to register a Poller.
<programlisting language="xml"><![CDATA[<int-xmpp:presence-outbound-channel-adapter id="pollingOutboundPresenceAdapter"
@@ -178,7 +180,7 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
<int:poller fixed-rate="1000" max-messages-per-poll="1"/>
</int-xmpp:presence-outbound-channel-adapter>]]></programlisting>
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.
</para>
</section>
</section>
@@ -186,17 +188,17 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
<title>Appendices</title>
<para>
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.
</para>
<para>
As stated earlier the <code>xmpp-connection</code> namespace support is designed to simplify basic connection configuration and
only supports a few common configuration attributes. However, the <classname>org.jivesoftware.smack.ConnectionConfiguration</classname>
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 <classname>XmppConnectionFactoryBean</classname> as a regular bean injecting
<classname>org.jivesoftware.smack.ConnectionConfiguration</classname> 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 <classname>XmppConnectionFactoryBean</classname> as a regular bean, and inject a
<classname>org.jivesoftware.smack.ConnectionConfiguration</classname> 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:
<programlisting language="xml"><![CDATA[<bean id="xmppConnection" class="org.springframework.integration.xmpp.XmppConnectionFactoryBean">
<constructor-arg>
@@ -214,26 +216,26 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/xmpp
xmpp-connection="xmppConnection"/>]]></programlisting>
</para>
<para>
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 <classname>SASLAuthentication</classname> 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 <classname>SASLAuthentication</classname>, 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.
<programlisting language="java"><![CDATA[@Configuration
public class CustomConnectionConfiguration {
@Bean
public XmppConnection knight() {
public XMPPConnection xmppConnection() {
SASLAuthentication.supportSASLMechanism("EXTERNAL", 0); // static initializer
ConnectionConfiguration config = new ConnectionConfiguration("localhost", 5223);
config.setTrustorePath("path_to_truststore.jks");
config.setSecurityEnabled(true);
config.setSocketFactory(SSLSocketFactory.getDefault());
conn = new XMPPConnection(config);
return new XMPPConnection(config);
}
}]]></programlisting>
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
</para>
</section>