BOLT Invocation Types - SOFARPC| Alibaba Cloud Documentation Center

SOFARPC provides a variety of invocation types under the Bolt protocol to meet different scenarios.

Sync invocation

For the Sync invocation, the client initiates a call, and then waits for the server to return the result before executing subsequent operations. This is the default invocation type of SOFARPC.

Asynchronous invocation

For the Future method, the client initiates a call and continues to execute the subsequent business logic without waiting for the server to return the result. SOFARPC caches the results returned by the server, and actively calls the API to obtain the results when the client needs them. To set the Future calling method for a service, you need to configure the type attribute. There are three types of asynchronous invocation, namely future, callback and oneway.

Future invocation

After Future invocation, the consumer side return immediately. When the consumer side needs the result, it needs to get data actively. There are 3 configuration ways as follows:

XML: In the XML, you need to set thetype attribute of the <sofa:global-attrs> tag to future.

<sofa:reference interface="com.example.demo.SampleService" id="sampleService">
    <sofa:binding.bolt>
        <sofa:global-attrs type="future"/>
    </sofa:binding.bolt>
</sofa:reference>

Annotation: By annotation, you need to set the invokeType attribute of @SofaReferenceBinding to future.

@SofaReference(binding = @SofaReferenceBinding(bindingType = "bolt", invokeType = "future"))
private SampleService sampleService;

API

configure as a Spring project: When using an API in a Spring project, set the type attribute of BoltBindingParam.
```
BoltBindingParam boltBindingParam = new BoltBindingParam();
boltBindingParam.setType("future");
```

configure without a Spring framework: When using raw APIs of SOFARPC in a non-Spring environment, set the invokeType attribute of ConsumerConfig.

ConsumerConfig<SampleService> consumerConfig = new ConsumerConfig<SampleService>()
.setInterfaceId(SampleService.class.getName())
.setRegistry(registryConfig)
.setProtocol("bolt")
.setInvokeType("future");

For the Future method, two methods are currently available to obtain the results of an asynchronous call.

Obtain the result directly: You can directly obtain the result of an asynchronous call in the following way:
```
String result = (String)SofaResponseFuture.getResponse(0, true);
```
Note:
- The first parameter indicates the timeout duration for obtaining the result.
- The second parameter indicates whether to clear the content in the thread context.
Obtain JDK native Future object: You can obtain the native Future object of JDK in the following way, and then call the Future object from anywhere to obtain the result.
```
Future future = SofaResponseFuture.getFuture(true);
```
Note: The first parameter indicates whether to clear the content in the thread context.

Callback invocation

With the callback method of SOFARPC Bolt protocol, SOFARPC does not need to wait for the result after initiating a call. After the client receives the result returned by the server, SOFARPC automatically calls a callback interface implemented by the user.

To use the callback method, you first need to implement a callback interface, set the callback interface in the corresponding configuration, and set the call method to callback. The details are as follows:

Implement the callback interface: SOFARPC provides a callback interface com.alipay.sofa.rpc.core.invoke.SofaResponseCallback. To use the callback method under the Bolt protocol, you need to implement the interface. The interface provides the following 3 methods:
- onAppResponse: When the client receives a normal response from the server, SOFARPC calls back the method.
- onAppException: When the client receives an abnormal response from the server, SOFARPC calls back the method.
- onSofaException: When an error, such as a routing error, occurs in SOFARPC, SOFARPC calls back the method.
Configure the callback interface at service level:
After implementing the callback interface, you need to set the implementation class in the corresponding service reference configuration, and set the call method to callback.

SOFARPC provides 2 methods for setting the callback interface: Callback Class and Callback Ref. Callback Class directly sets the class name of the callback. SOFARPC generates an instance of the callback class by calling the default constructor of the callback class. However, Callback Ref directly provides the instance of the callback class.

There are 3 configuration ways as follows:
- XML: If the service is referenced through the XML mode, set the type attribute of the <sofa:global-attrs> tag to callback, and set the callback-ref or callback-class attributes.
```
<bean id="sampleCallback" class="com.example.demo.SampleCallback"/>
<sofa:reference interface="com.example.demo.SampleService" id="sampleService">
<sofa:binding.bolt>
  <sofa:global-attrs type="callback" callback-ref="sampleCallback"/>
</sofa:binding.bolt>
</sofa:reference>
```
  In the XML mode, the value of callback-ref must be the Bean name of the callback class.
- Annotation: If the service is referenced through the Annotation mode, set the invokeType attribute of the @SofaReferenceBinding annotation to callback, and set the callbackClass or callbackRef attributes.
```
@SofaReference(binding = @SofaReferenceBinding(bindingType = "bolt",
      invokeType = "callback",
      callbackRef = "sampleCallback"))
private SampleService sampleService;
```
  In the Annotation mode, the value of the callbackRef attribute must be the Bean name of the callback class.
- API:
  - configure as a Spring project: When using an API in the Spring or Spring Boot environment, set the type attribute of BoltBindingParam to callback, and set the callbackClass or callbackRef attributes.
```
BoltBindingParam boltBindingParam = new BoltBindingParam();
boltBindingParam.setType("callback");
boltBindingParam.setCallbackClass("com.example.demo.SampleCallback");
```
  - configure without a Spring framework: When using raw APIs of SOFARPC in a non-Spring environment, call setInvokeType to set the call method to callback, and call setOnReturn to set the callback class.
```
ConsumerConfig<SampleService> consumerConfig = new ConsumerConfig<SampleService>()
.setInterfaceId(SampleService.class.getName())
.setRegistry(registryConfig)
.setProtocol("bolt")
.setInvokeType("callback")
.setOnReturn(new SampleCallback());
```
Configure the callback interface at invocation level:
You can configure the callback interface at the invocation level in the following way:

RpcInvokeContext.getContext().setResponseCallback(new SampleCallback());

Oneway invocation

The Oneway method applies when the client does not care about the result of a request sent to the server. Null is returned immediately after the call is initiated, and the client ignores the result returned from the server.

To use the Oneway method, set the call method to oneway in the same way as setting the call method to future or callback as mentioned above.

Note that if you use the Oneway method, all timeout settings are invalid, because the result is immediately returned.