<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="httpinvoker"
    xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>HttpInvoker Support</title>
  
  <section id="httpinvoker-intro">
    <title>Introduction</title>
    <important>
    This module is DEPRECATED and will be removed in future releases of Spring Integration. Please use HTTP support (<xref linkend="http"/>) which should
    provide all the functionality that was available with Http Invoker plus more.
    </important>
    <para>
      HttpInvoker is a Spring-specific remoting option that essentially enables Remote Procedure Calls (RPC) over HTTP.
      In order to accomplish this, an outbound representation of a method invocation is serialized using standard Java
      serialization and then passed within an HTTP POST request. After being invoked on the target system, the method's
      return value is then serialized and written to the HTTP response. There are two main requirements. First, you
      must be using Spring on both sides since the marshalling to and from HTTP requests and responses is handled by
      the client-side invoker and server-side exporter. Second, the Objects that you are passing must implement
      <interfacename>Serializable</interfacename> and be available on both the client and server.
    </para>
    <para>
      While traditional RPC provides <emphasis>physical</emphasis> decoupling, it does not offer nearly the same degree
      of <emphasis>logical</emphasis> decoupling as a messaging-based system. In other words, both participants in an
      RPC-based invocation must be aware of a specific interface and specific argument types. Interestingly, in Spring
      Integration, the "parameter" being sent is a Spring Integration Message, and the interface is an internal detail
      of Spring Integration's implementation. Therefore, the RPC mechanism is being used as a
      <emphasis>transport</emphasis> so that from the end user's perspective, it is not necessary to consider the
      interface and argument types. It's just another adapter to enable messaging between two systems.
    </para>
  </section>

  <section id="httpinvoker-inbound">
    <title>HttpInvoker Inbound Gateway</title>
    <para>
    To receive messages over http you can use an <classname>HttpInvokerInboundGateway</classname>. Here is an
    example bean definition:
    <programlisting language="xml"><![CDATA[<bean id="inboundGateway"
      class="org.springframework.integration.httpinvoker.HttpInvokerInboundGateway">
    <property name="requestChannel" ref="requestChannel"/>
    <property name="replyChannel" ref="replyChannel"/>
    <property name="requestTimeout" value="30000"/>
    <property name="replyTimeout" value="10000"/>
</bean>]]></programlisting>
    Because the inbound gateway must be able to receive HTTP requests, it must be configured within a Servlet
    container. The easiest way to do this is to provide a servlet definition in <emphasis>web.xml</emphasis>:
    <programlisting language="xml"><![CDATA[<servlet>
    <servlet-name>inboundGateway</servlet-name>
    <servlet-class>org.springframework.web.context.support.HttpRequestHandlerServlet</servlet-class>
</servlet>]]></programlisting>
    Notice that the servlet name matches the bean name.
    <note>
      If you are running within a Spring MVC application and using the BeanNameHandlerMapping, then the servlet
      definition is not necessary. In that case, the bean name for your gateway can be matched against the URL
      path just like a Spring MVC Controller bean.
    </note>
    </para>
  </section>

  <section id="httpinvoker-outbound">
    <title>HttpInvoker Outbound Gateway</title>
    <para>
  </para>
  <para>
    To configure the <classname>HttpInvokerOutboundGateway</classname> write a bean definition like this:
    <programlisting language="xml"><![CDATA[<bean id="outboundGateway"
      class="org.springframework.integration.httpinvoker.HttpInvokerOutboundGateway">
    <property name="replyChannel" ref="replyChannel"/>
</bean>]]></programlisting>
    The outbound gateway is a <interfacename>MessageHandler</interfacename> and can therefore be registered with
    either a <classname>PollingConsumer</classname> or <classname>EventDrivenConsumer</classname>.
    The URL must match that defined by an inbound HttpInvoker Gateway as described in the previous section.
    </para>
  </section>

  <section id="httpinvoker-namespace">
    <title>HttpInvoker Namespace Support</title>
  <para>
    Spring Integration provides an "httpinvoker" namespace and schema definition. To include it in your
    configuration, simply provide the following URI within a namespace declaration:
    'http://www.springframework.org/schema/integration/httpinvoker'. The schema location should then map to
    'http://www.springframework.org/schema/integration/httpinvoker/spring-integration-httpinvoker-2.0.xsd'.
  </para>
    <para>
    To configure the inbound gateway you can choose to use the namespace support for it. The following code snippet shows the different configuration options that are supported.
    <programlisting language="xml"><![CDATA[<httpinvoker:inbound-gateway id="inboundGateway"
                             request-channel="requestChannel"
                             request-timeout="10000"
                             expect-reply="false"
                             reply-timeout="30000"/>]]></programlisting>
    <note>
      A 'reply-channel' may also be provided, but it is recommended to rely on the temporary anonymous channel
      that will be created automatically for handling replies.
    </note>
    </para>
    <para>
    To configure the outbound gateway you can use the namespace support as well. The following code snippet shows the different configuration for an outbound HttpInvoker gateway. Only the 'url' and 'request-channel' are required.
    <programlisting language="xml"><![CDATA[<httpinvoker:outbound-gateway id="outboundGateway"
                              url="http://localhost:8080/example"
                              request-channel="requestChannel"
                              request-timeout="5000"
                              reply-channel="replyChannel"
                              reply-timeout="10000"/>]]></programlisting>
    </para>
  </section>
</chapter>
