Bug 778463 (SOA-939)

Link: Added: This issue is related to JBESB-2114

First example in chapter 3 needs to include invmScope="GLOBAL"

And serveral  paragraphs after it needs some changes:

The Endpoint addresses made available to the ServiceInvoker will depend on the list of listeners configured on the Service, such as JMS, FTP or HTTP. No listeners are configured on the Service in the above example, but its InVM listener has been enabled using invmScope="GLOBAL". The InVM transport is a new feature in JBossESB 4.3 that provides communication between services running on the same JVM.   Section 4.3.3, "InVM Transport" contains more information about this feature.

Section 4.3.3 also has to be updated.
Revised content:

4.3.3. InVM Transport
The InVM transport is a new feature in JBossESB 4.3 that provides communication between services running on the same JVM. This means that instances of ServiceInvoker can invoke a service from within the same JVM without any networking or message serialization overhead.  

The default InVM Scope for an ESB deployment is specified in the jbossesb-properties.xml file  using the core:jboss.esb.invm.scope.default property. The supplied configured value is NONE however  if this property is undefined the default scope is actually GLOBAL.

The JBossESB currently supports 2 scopes.
NONE
      The Service is not invokable over the InVM transport. JBossESB is configured with this as the
      default value.
GLOBAL
      The Service is invokable over the InVM transport from within the same Classloader scope.

A LOCAL scope will be added in a future release, which will restrict invocation to within the same deployed .esb archive.

Each service can specify their own InVM scope in the invmScope attribute on the <service> element
of their services configuration.
    <service category="ServiceCat" name="ServiceName" invmScope="GLOBAL"
       description="Test Service">
       <actions mep="RequestResponse">
          <action name="action"
             class="org.jboss.soa.esb.listeners.SetPayloadAction">
             <property name="payload" value="Tom Fennelly" />
          </action>
       </actions>
    </service>
Example 4.2. Enabling GLOBAL inVM scope for a service

Lock-step Delivery
The InVM Transport delivers messages with low overhead to an in-memory message queue. This is very fast and the message queue can become overwhelmed if delivery is happening too quickly for the Service consuming the messages. To mitigate these situations the InVM transport provides a "Lock-Step" delivery mechanism.

The "Lock-Step" delivery method attempts to ensure that messages are not delivered to a service faster than the service is able to retreive them. It does this by blocking message delivery until the receiving Service picks up the message or a timeout period expires.

This is not a synchronous delivery method. It does not wait for a response or for the service to process the message. It only blocks until the message is removed from the queue by the service.

Lock Step delivery is disabled by default, but can be easily enabled for a service using it's <property>
settings on the <service>:

inVMLockStep
     A boolean value controlling whether LockStep delivery is enabled

inVMLockStepTimeout
     The maximum number of milliseconds that message delivery will be blocked while waiting for a
     message to be retreived.

    <service category="ServiceCat" name="Service2"
      description="Test Service">
      <property name="inVMLockStep" value="true" />
      <property name="inVMLockStepTimeout" value="4000" />
      <actions mep="RequestResponse">
         <action name="action" class="org.jboss.soa.esb.mock.MockAction" />
      </actions>
    </service>
Example 4.3. Enabling "Lock-Step" delivery

Load Balancing
When using the ServiceInvoker, preference is always given to invoking a service over its InVM transport if one is available. Other load balancing strategies are only be applied in the absence of an InVM endpoint for the target Service.

Transaction Semantics
The InVM transport in JBossESB is not transactional and the message queue is held only in volatile memory. This means that the Message Queue for this transport will be lost in the case of system failure or shutdown.

content added.  JBESB-2114 created for updating this content in the upstream docs

Verified in CR1