SOFA-RPC User Guide

Edit
Update time: 2021-09-16

SOFA-RPC Interface Sectioon

  • Introduce the jar packages into your interface project.
      <dependency>
          <groupId>org.dromara</groupId>
          <artifactId>hmily-annotation</artifactId>
          <version>{last.version}</version>
      </dependency>
  • Add the @Hmily annotation on the interface method in which you need to perform Hmily distributed transactions.

    public interface HelloService {
    
    @Hmily
    void say(String hello);
    }
    

    The project with SOFA-RPC implementation

    • Step 1 : Introduce the jar package of the hmily dependency

    • Step 2 : Add Hmily configuration

    • Step 3 : Add the specific annotation to the implementation method. you need to complete the development of confirm and cancel method, if in TCC mode.

    Introduce The Maven dependency

    Spring-Namespace
    • Introduce the hmily-sofa-rpc dependency
        <dependency>
            <groupId>org.dromara</groupId>
            <artifactId>hmily-sofa-rpc</artifactId>
           <version>{last.version}</version>
        </dependency>
    
  • make the configuration in the XML configuration file as below:

    <!-- set up to enable the aspectj-autoproxy -->
    <aop:aspectj-autoproxy expose-proxy="true"/>
    <bean id = "hmilyTransactionAspect" class="org.dromara.hmily.spring.aop.SpringHmilyTransactionAspect"/>
    <bean id = "hmilyApplicationContextAware" class="org.dromara.hmily.spring.HmilyApplicationContextAware"/>

Spring-Boot
  • Introduce the hmily-spring-boot-starter-sofa-rpc dependency
        <dependency>
            <groupId>org.dromara</groupId>
            <artifactId>hmily-spring-boot-starter-sofa-rpc</artifactId>
           <version>{last.version}</version>
        </dependency>

Introduce the Hmily configuration

Add annotations on the implementation interface

We have completed the integration described above,and the next we will talk about the specific implementation.

TCC Mode
  • Add @HmilyTCC (confirmMethod = "confirm", cancelMethod = "cancel") annotation to the concrete implementation of the interface method identified by ‘@Hmily’.

  • confirmMethod : the method name for confirm,The method parameter list and return type should be consistent with the identification method.

  • cancelMethod : the method for cancel,The method parameter list and return type should be consistent with the identification method.

  • The TCC mode should ensure the idempotence of the confirm and cancel methods,Users need to develop these two methods by themselves,The confirmation and rollback behavior of all transactions are completely up tp users.The Hmily framework is just responsible for making calls.


public class HelloServiceImpl implements HelloService  {

    @HmilyTCC(confirmMethod = "sayConfrim", cancelMethod = "sayCancel")
    public void say(String hello) {
         System.out.println("hello world");
    }
    
    public void sayConfrim(String hello) {
         System.out.println(" confirm hello world");
    }

    public void sayCancel(String hello) {
         System.out.println(" cancel hello world");
    }
}

TAC Mode(Under development, not released)

  • Add @HmilyTAC annotation to the concrete implementation of the interface method identified by ‘@Hmily’.

Important Notes

Before invoking any RPC calls, when you need to aggregate RPC calls to be a distributed transaction, you need to add an annotation to the method of aggregate RPC calls which means to enable a global transaction.

Load balance && Set up to never try

  • If the service is deployed with several nodes, the load balance algorithm is better to use hmily, so that the calls of try, confirm, and cancel will fall on the same node to make full use of the cache and improve efficiency.

  • There are serval load balance algorithms supported such as hmilyConsistentHash, hmilyRandom, hmilyLocalPref, hmilyRoundRobin, hmilyWeightRoundRobin, hmilyWeightConsistentHash, all of which are inherited from SOFA-RPC’s native algorithm.

      <sofa:reference jvm-first="false" id="accountService" interface="org.dromara.hmily.demo.common.account.api.AccountService">
           <sofa:binding.bolt>
               <sofa:global-attrs retries="0" timeout="5000" loadBalancer ="hmilyRandom"/>
           </sofa:binding.bolt>
       </sofa:reference>       

Exception

  • Do not catch any exceptions of the try, confirm, cancel method by yourself. Any exceptions should be thrown to the Hmily framework to handle.