Configure Bolt services

In SOFA, Bolt service providers use port 12200. For more information, see Configuration description.

Publish and reference Bolt services

In SOFA, RPC uses a binding model to define communication protocols. Each new protocol requires a new binding model. To implement the Bolt protocol for RPC in SOFA, add a <sofa:binding.bolt/> tag to the binding model.

• To publish a Bolt service, add <sofa:binding.bolt/> to <sofa:service>. For example:

  <!-- Publish a Bolt service -->
  <sofa:service interface="com.alipay.test.SampleService" ref="sampleService" unique-id="service1">
       <sofa:binding.bolt/>
  </sofa:service>

• To reference a Bolt service, add <sofa:binding.bolt/> to <sofa:reference>. For example:

  <!-- Reference a Bolt service -->
  <sofa:reference interface="com.alipay.test.SampleService" id="sampleService">
       <sofa:binding.bolt/>
  </sofa:reference>

Complete Bolt service configuration

The main Bolt configuration tags are global-attrs and method. If both are configured, the configuration in method takes precedence. The configurable parameters are as follows:

• type: The invocation method. Valid values are sync, oneway, callback, and future. The default value is sync.

• timeout: The timeout period. The default value is 3000 ms.

• callback-class: The callback object class for the callback invocation method.

• callback-ref: The Spring Bean reference for the callback invocation method.

Complete Bolt service publishing configuration

<sofa:service interface="com.alipay.test.SampleService" ref="sampleService" unique-id="service1">
    <sofa:binding.bolt>
        <sofa:global-attrs timeout="5000"/>
        <!-- The method name "service" is an example. Replace it with the actual method name. -->
        <sofa:method name="service" timeout="3000"/>
    </sofa:binding.bolt>
</sofa:service>

Complete Bolt service reference configuration

<sofa:reference id="sampleService" interface="com.alipay.test.SampleService" unique-id="service1">
    <sofa:binding.bolt>
        <sofa:global-attrs timeout="5000" test-url="localhost:12200" address-wait-time="1000"
            connect.timeout="1000" connect.num="-1" idle.timeout="-1" idle.timeout.read="-1"/>
        <!-- Properties configured in method have a higher priority than those in global-attrs. -->
        <!-- The method names "futureMethod" and "callbackMethod" are examples. Replace them with the actual method names. -->
        <sofa:method name="futureMethod" type="future" timeout="5000"/>
        <sofa:method name="callbackMethod" type="callback" timeout="3000"
            callback-class="com.alipay.test.TestCallback"/>
    </sofa:binding.bolt>
</sofa:reference>

Bolt service provider configuration

The underlying service provider for Bolt is a Java Non-blocking I/O (NIO) Server. The SOFA framework provides several options to adjust the properties of the Bolt Server. For more information, see Configuration description.

Bolt service consumer configuration

Bolt reference invocation methods

Bolt provides multiple invocation methods to meet various business requirements. The available invocation methods are as follows:

• sync invocation

  This is the default invocation method for Bolt. You can configure timeout periods on the service provider and the service consumer:

  • Service provider

    The XML configuration is as follows:

    <!-- Provider-side timeout configuration -->
    <sofa:service interface="com.alipay.test.SampleService2" ref="sampleService2">
        <sofa:binding.bolt>
        <!-- The method name "service" is an example. Replace it with the actual method name. -->
        <sofa:method name="service" timeout="5000"/>
        </sofa:binding.bolt>
    </sofa:service>

  • Service consumer

    The XML configuration is as follows:

    <!-- Consumer-side timeout configuration -->
    <sofa:reference interface="com.alipay.test.SampleService2" id="sampleServiceSync">
        <sofa:binding.bolt>
             <!-- Global timeout configuration -->
              <sofa:global-attrs timeout="8000" test-url="127.0.0.1:12200"/>
              <!-- If method is configured, its configuration takes precedence. -->
              <!-- The method name "service" is an example. Replace it with the actual method name. -->
              <sofa:method name="service" type="sync" timeout="10000"/>
        </sofa:binding.bolt>
    </sofa:reference>

    The default value of type is sync. If you have multiple methods that require the same timeout period, you can set a global timeout period. The XML configuration is as follows:

    <!-- Batch configuration of consumer-side timeout -->
    <sofa:reference interface="com.alipay.test.SampleService2" id="sampleServiceSync">
         <sofa:binding.bolt>
              <sofa:global-attrs timeout="5000" test-url="127.0.0.1:12200"/>
         </sofa:binding.bolt>
    </sofa:reference>

    Note

    If you configure a timeout period on the consumer side, it takes precedence over the provider-side timeout. If you do not configure a timeout on the consumer side, the provider-side timeout is used. The priority of timeout configurations is as follows: reference method > reference global-attrs > service method > service global-attrs.

• oneway invocation

  In a oneway invocation, the consumer does not wait for a result. The consumer returns immediately after making the call, and the framework ignores the provider's processing result. In Bolt, you can configure the method in XML as follows:

  <!-- Configure oneway -->
  <sofa:reference interface="com.alipay.test.SampleService2" id="sampleService2">
      <sofa:binding.bolt>
          <sofa:global-attrs test-url="127.0.0.1:12200"/>
          <!-- The method name "service" is an example. Replace it with the actual method name. -->
          <sofa:method name="service" type="oneway"/>
      </sofa:binding.bolt>
  </sofa:reference>

  Note

  Because the consumer returns immediately and does not wait for the result, configuring the timeout property has no effect for oneway invocations.

• callback invocation

  Callback is an asynchronous invocation method where the consumer provides a callback interface. After the call is completed, the framework invokes the callback interface. You can implement the callback interface by configuring a class or by referencing a Bean:

  • Configure a class

    The XML configuration is as follows:

    <!-- Callback invocation configuration -->
    <sofa:reference interface="com.alipay.test.SampleService2" id="sampleService">
        <sofa:binding.bolt>
            <!-- The method name "testCallback" is an example. Replace it with the actual method name. -->
            <sofa:method name="testCallback" type="callback" callback-class="com.alipay.test.binding.tr.MyCallBackHandler"/>
        </sofa:binding.bolt>
    </sofa:reference>

  • Reference a Bean

    The XML configuration is as follows:

    <!-- Use a Bean to implement the callback interface -->
    <bean id="myCallBackHandlerBean"class="com.alipay.test.binding.tr.MyCallBackHandler"/>
    <sofa:reference interface="com.alipay.test.SampleService2" id="sampleService">
        <sofa:binding.bolt>
            <!-- The method name "testCallback" is an example. Replace it with the actual method name. -->
            <sofa:method name="testCallback" type="callback" callback-ref="myCallBackHandlerBean"/>
        </sofa:binding.bolt>
    </sofa:reference>

When you use the callback invocation method, the callback interface must implement com.alipay.sofa.rpc.api.callback.SofaResponseCallback. This interface contains the following three methods:

public interface SofaResponseCallback {

  /**
   * The sofa-remoting layer calls this method when the service provider's business layer returns a result normally.
   * @param appResponse response object.
   * @param methodName The name of the invoked service method.
   * @param request The request corresponding to the callback.
   `*/
  public void onAppResponse(Object appResponse, String methodName, RequestBase request);

  /**
   * The sofa-remoting layer calls this method when the service provider's business layer throws an exception.
   * @param t The exception thrown by the provider's business layer.
   * @param methodName The name of the invoked service method.
   * @param request The request corresponding to the callback.
   `*/
  public void onAppException(Throwable t, String methodName, RequestBase request);

  /**
   * The sofa-remoting layer calls this method when an exception occurs in the sofa-remoting layer.
   * @param sofaException The exception from the sofa-remoting layer.
   * @param methodName The name of the invoked service method.
   * @param request The request corresponding to the callback.
   `*/
  public void onSofaException(SofaRpcException sofaException, String methodName,
                             RequestBase request);

}

• future invocation

  Future is another asynchronous invocation method. The consumer returns immediately after making a call. When the result is needed, the consumer must actively retrieve the data. The configuration for a future invocation is similar to other methods. You can set the type to future at the method level. The XML configuration is as follows:

  <!-- Future invocation configuration -->
  <sofa:reference interface="com.alipay.test.SampleService" id="sampleServiceFuture">
      <sofa:binding.bolt>
          <sofa:global-attrs test-url="127.0.0.1:12200"/>
          <!-- The method name "service" is an example. Replace it with the actual method name. -->
          <sofa:method name="service" type="future"/>
      </sofa:binding.bolt>
  </sofa:reference>

  For a future invocation, the result is saved in a ThreadLocal variable. You can retrieve the value of this thread variable as follows:

  // Get the result of the future invocation.
  public void testFuture() throws SofaException, InterruptedException {
    sampleServiceFuture.service();
    Object result = SofaResponseFuture.getResponse(1000, true);
  
    Assert.assertEquals("Hello, world!", result);
  }

  To retrieve the result of a future invocation, you can call the getResponse method of SofaResponseFuture. The two parameters of the getResponse method are described below:

  • The first parameter is the timeout period. It specifies the maximum time that the calling thread waits. A negative value indicates no time limit, and a value of zero indicates an immediate return. The unit is milliseconds.

  • The second parameter specifies whether to clear the value of the ThreadLocal variable. If you set this parameter to true, the ThreadLocal value is cleared before the response is returned. This prevents memory leaks.

Detailed Bolt reference configuration

In addition to the various invocation methods, Bolt provides several configuration options on the consumer side. These options are less common and are listed below: