All Products
Search
Document Center

BOLT Configuration in SOFARPC

Last Updated: Aug 17, 2020

The name of Bolt comes from the underlying communication framework Bolt used by RPC. Bolt outperforms traditional WebService because it supports complex objects, has smaller serialized objects, provides multiple invocation types (such as sync, oneway, callback, and future), and supports a wide range of scenarios.

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

Publish and reference Bolt services

In SOFA, the RPC defines different communication protocols through Binding models. When a new protocol is introduced, a Binding model is added. To add the Bolt protocol of RPC in SOFA, you need to add <sofa:binding.bolt/> to the Binding model.

  • To publish a Bolt service, add <sofa:binding.bolt/> in <sofa:service>:
  1. <! -- Publish a Bolt service -->
  2. <sofa:service interface="com.alipay.test.SampleService"
  3. ref="sampleService" unique-id="service1">
  4. <sofa:binding.bolt/>
  5. </sofa:service>
  • To reference a Bolt service, add <sofa:binding.bolt/> in <sofa:reference>:
  1. <! -- Reference a Bolt service -->
  2. <sofa:reference interface="com.alipay.test.SampleService" id="sampleService">
  3. <sofa:binding.bolt/>
  4. </sofa:reference>

Configure the Bolt service provider

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

Configure the Bolt service consumer

Bolt reference and call methods

Bolt provides multiple call methods to meet the requirements of different business scenarios. Currently, the following call methods available:

Call method Type Description
sync Sync The default call method of Bolt.
oneway Send messages in asynchronous mode The call is completed immediately after the consumer sends a request. The processing result of the provider is ignored.
callback Send messages in asynchronous mode The consumer provides a callback interface. The SOFA framework calls the callback interface after the provider returns a response.
future Send messages in asynchronous mode The call is completed immediately after the consumer initiates the call. If the consumer needs the result, it needs to be actively acquired.
Sync

The default call method of Bolt. Bolt supports to configure the timeout period on the service provider side. The XML configuration is as follows:

  1. <! -- Timeout configuration on the service provider side -->
  2. <sofa:service interface="com.alipay.test.SampleService2" ref="sampleService2">
  3. <sofa:binding.bolt>
  4. <! -- You need to replace "service" with the actual method name. -->
  5. <sofa:method name="service" timeout="5000" />
  6. </sofa:binding.bolt>
  7. </sofa:service>

Note: The priority of the timeout configuration is as follows:

  • The setting on consumer side will prevail with timeout configured both on consumer and provider.
  • The setting on provider side will be effective with the absence of it on consumer side.
  • Other priorities of timeout from high to low is as follows: Reference method > Reference global-attrs > Service method > Service global-attrs.

The configuration on the consumer side is similar to that on the provider side. The XML configuration is as follows:

  1. <! -- Timeout configuration on the consumer side -->
  2. <sofa:reference interface="com.alipay.test.SampleService2" id="sampleServiceSync">
  3. <sofa:binding.bolt>
  4. <! -- Global timeout configuration -->
  5. <sofa:global-attrs timeout="8000" test-url="127.0.0.1:12200" />
  6. <! -- The setting for "method" prevails if configured -->
  7. <! -- You need to replace "service" with the actual method name. -->
  8. <sofa:method name="service" type="sync" timeout="10000" />
  9. </sofa:binding.bolt>
  10. </sofa:reference>

The default value of type is sync if the parameter is not configured. To configure the same timeout period for multiple methods, you can set a global timeout period.

  1. <! -- Configure a global timeout period on the consumer side-->
  2. <sofa:reference interface="com.alipay.test.SampleService2" id="sampleServiceSync">
  3. <sofa:binding.bolt>
  4. <sofa:global-attrs timeout="5000" test-url="127.0.0.1:12200" />
  5. </sofa:binding.bolt>
  6. </sofa:reference>
Oneway

For the Oneway method, the consumer does not care about the result and completes a call immediately after initiating it, and the framework ignores the processing result of the provider. In Bolt, the configuration of method in the XML mode is as follows:

  1. <! -- Configure the Oneway method -->
  2. <sofa:reference interface="com.alipay.test.SampleService2" id="sampleService2">
  3. <sofa:binding.bolt>
  4. <sofa:global-attrs test-url="127.0.0.1:12200" />
  5. <! -- You need to replace "service" with the actual method name. -->
  6. <sofa:method name="service" type="oneway"/>
  7. </sofa:binding.bolt>
  8. </sofa:reference>

Note: The timeout setting in Oneway mode is invalid, because the consumer does not care about the processing result and completes a call directly after initiating it.

  1. <! -- The timeout setting is invalid -->
  2. <sofa:reference interface="com.alipay.test.SampleService2" id="sampleService">
  3. <sofa:binding.bolt>
  4. <sofa:global-attrs test-url="127.0.0.1:12200" />
  5. <! -- You need to replace "service" with the actual method name. -->
  6. <sofa:method name="service" type="oneway" timeout="1000" />
  7. </sofa:binding.bolt>
  8. </sofa:reference>
Callback

Callback is an asynchronous callback method. In this case, the consumer needs to provide a callback interface to be invoked by the framework after the provider process completes. The following is the XML configuration:

  1. <! -- Callback configuration -->
  2. <sofa:reference interface="com.alipay.test.SampleService2" id="sampleService">
  3. <sofa:binding.bolt>
  4. <! -- You need to replace "testCallback" with the actual method name -->
  5. <sofa:method name="testCallback" type="callback" callback-class="com.alipay.test.binding.tr.MyCallBackHandler" />
  6. </sofa:binding.bolt>
  7. </sofa:reference>

The above callback interface is implemented through class configuration. SOFA provides another way to implement callback by referencing a Bean object.

  1. <! -- Use a Bean object to implement the callback interface -->
  2. <bean id="myCallBackHandlerBean" class="com.alipay.test.binding.tr.MyCallBackHandler" />
  3. <sofa:reference interface="com.alipay.test.SampleService2" id="sampleService">
  4. <sofa:binding.bolt>
  5. <! -- You need to replace "testCallback" with the actual method name -->
  6. <sofa:method name="testCallback" type="callback" callback-ref="myCallBackHandlerBean" />
  7. </sofa:binding.bolt>
  8. </sofa:reference>

Note that the callback interface must implement interface com.alipay.sofa.rpc.api.callback.SofaResponseCallback, which defines three methods:

  1. public interface SofaResponseCallback {
  2. /**
  3. * When the service provider returns the result normally, the sofa-remoting layer calls back this method.
  4. * @param appResponse response object
  5. * @param methodName: method name corresponding to the invoked service
  6. * @param request: request corresponding to callback
  7. `*/
  8. public void onAppResponse(Object appResponse, String methodName, RequestBase request);
  9. /**
  10. * When the service provider throws an exception, the sofa-remoting layer calls back this method.
  11. * @param t: the exception thrown by the business layer of service provider.
  12. * @param methodName: method name corresponding to the invoked service
  13. * @param request: request corresponding to callback
  14. `*/
  15. public void onAppException(Throwable t, String methodName, RequestBase request);
  16. /**
  17. * When an exception occurs on the sofa-remoting layer, this method is called back.
  18. * @param sofaException: the exception thrown by the sofa-remoting layer.
  19. * @param methodName: method name corresponding to the invoked service
  20. * @param request: request corresponding to callback
  21. `*/
  22. public void onSofaException(SofaRpcException sofaException, String methodName,
  23. RequestBase request);
  24. }
Future

Future is also an asynchronous calling method. The call is completed immediately after the consumer initiates the call. If the consumer needs the result, it needs to be actively acquired. To use the future method, the configuration is similar to the preceding configuration, except that the type of method should be set to future.

  1. <! -- Future configuration -->
  2. <sofa:reference interface="com.alipay.test.SampleService" id="sampleServiceFuture">
  3. <sofa:binding.bolt>
  4. <sofa:global-attrs test-url="127.0.0.1:12200" />
  5. <! -- You need to replace "service" with the actual method name. -->
  6. <sofa:method name="service" type="future"/>
  7. </sofa:binding.bolt>
  8. </sofa:reference>

For the Future method, the results returned are stored in ThreadLocal whose value can be obtained in the following way:

  1. // Obtain the calling result in Future mode
  2. public void testFuture() throws SofaException, InterruptedException {
  3. sampleServiceFuture.service();
  4. Object result = SofaResponseFuture.getResponse(1000, true);
  5. Assert.assertEquals("Hello, world!", result);
  6. }

To obtain the result of a Future call, call the getResponse method of SofaResponseFuture. The two parameters of getResponse method are described as follows:

  • The first parameter is the timeout period (in milliseconds), which means the maximum waiting time of the call thread. A negative value indicates that no limit apply to the waiting time, zero indicates that the result is immediately returned.
  • The second parameter indicates whether to delete the value of the ThreadLocal variable. If it is set to true, the value of ThreadLocal is deleted before the response is returned to avoid RAM leakage.

Detailed configuration of Bolt reference

In addition to the calling methods, Bolt provides different configuration options on the consumer side, which are usually not used:

Parameter Type Description Default value Value range
connect.timeout INTEGER Connection timeout period on the consumer side 1000 (ms) It is a positive integer in milliseconds (ms).
connect.num INTEGER Number of connections on the consumer side -1 -1 indicates that the number is not specified (one connection is set up for each target address by default).
idle.timeout INTEGER Maximum idle time on the consumer side -1 -1 indicates that the underlying default value is used (the value is 0, indicating reading idle time never occurs).
The configuration also indicates the interval of heartbeat signals. When the idle duration of a request exceeds the specified value, a heartbeat signal is sent to the server.
idle.timeout.read INTEGER Maximum reading idle period on the consumer side -1 -1 indicates that the underlying default value is used (the value is 30).
If idle.timeout is larger than 0, the connection breaks if no request occurs within the period of idle.timeout plus idle.timeout.read.
address-wait-time INTEGER Time of waiting for the registry to push the address to the consumer while generating a reference. 0 (ms) The maximum value is 30000 ms, and values exceeding 30000 ms is adjusted to 30000 ms.

Complete configuration of Bolt service

BOLT configuration tags include: global-attrs and method. If global-attrs and method are both configured, the configuration in method prevails. Configurable parameters include:

  • type: the call method. Valid values include sync, oneway, callback, and future. The default method is sync.
  • timeout: the timeout period. The default value is 3000 ms.
  • callback-class: the callback class when the call method is callback.
  • callback-ref: the callback Spring Bean reference when the call method is callback.

Complete configuration for BOLT service publication

  1. <sofa:service interface="com.alipay.test.SampleService" ref="sampleService" unique-id="service1">
  2. <sofa:binding.bolt>
  3. <sofa:global-attrs timeout="5000" />
  4. <! -- You need to replace "service" with the actual method name. -->
  5. <sofa:method name="service" timeout="3000"/>
  6. </sofa:binding.bolt>
  7. </sofa:service>

Complete configuration for BOLT service reference

  1. <sofa:reference id="sampleService" interface="com.alipay.test.SampleService" unique-id="service1">
  2. <sofa:binding.bolt>
  3. <sofa:global-attrs timeout="5000" test-url="localhost:12200" address-wait-time="1000"
  4. connect.timeout="1000" connect.num="-1" idle.timeout="-1" idle.timeout.read="-1"/>
  5. <! -- The priority of configuration in "method" is higher than that in "global-attrs" -->
  6. <! -- You need to replace "futureMethod" and "callbackMethod" with the actual method names -->
  7. <sofa:method name="futureMethod" type="future" timeout="5000" />
  8. <sofa:method name="callbackMethod" type="callback" timeout="3000"
  9. callback-class="com.alipay.test.TestCallback" />
  10. </sofa:binding.bolt>
  11. </sofa:reference>