Using API

SOFA provides a mechanism to store programming APIs of various components, as well as a unified method for you to obtain these APIs. The unified method is the ClientFactory class. You can store and obtain the programming APIs of components through ClientFactory. SOFA provides two ways to obtain the ClientFactory class:

• Implement the ClientFactoryAware interface
• Use the @SofaClientFactory annotation

When using the programming related APIs of components in SOFA, ensure that the following dependency has been added to the module:

<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>rpc-enterprise-sofa-boot-starter</artifactId>
</dependency>

Obtain the ClientFactory class

Implement the ClientFactoryAware interface

The first way to obtain the ClientFactory class is to implement the ClientFactoryAware interface. The following shows the code example:

public class ClientFactoryBean implements ClientFactoryAware {
    private ClientFactory clientFactory;
    @Override
    public void setClientFactory(ClientFactory clientFactory) {
        this.clientFactory = clientFactory;
    }
    public ClientFactory getClientFactory() {
        return clientFactory;
    }
}

Then, configure the above ClientFactoryBean as a Spring Bean.

<bean id="clientFactoryBean" class="com.alipay.test.ClientFactoryBean"/>

As a result, ClientFactoryBean can obtain the clientFactory object.

Use the @SofaClientFactory annotation

The second way to obtain the ClientFactory class is to use the @SofaClientFactory annotation. The following shows the code example:

public class ClientAnnotatedBean {
    @SofaClientFactory
    private ClientFactory clientFactory;
    public ClientFactory getClientFactory() {
        return clientFactory;
    }
}

Add the @SofaClientFactory annotation to the ClientFactory field, and configure ClientAnnotatedBean as a Spring Bean:

<bean id="clientAnnotatedBean" class="com.alipay.test.ClientAnnotatedBean"/>

As a result, the SOFA framework automatically injects the ClientFactory instance into the field annotated by @SofaClientFactory.

However, you can only obtain the ClientFactory object in this way. To obtain a specific client, such as ServiceFactory, you need to call the getClient method of ClientFactory. SOFA strengthens the @SofaClientFactory annotation so that you can directly use @SofaClientFactory to obtain the specific client. The following shows the code example:

public class ClientAnnotatedBean {
    @SofaClientFactory
    private ServiceClient serviceClient;
    public ServiceClient getServiceClient() {
        return serviceClient;
    }
}

When @SofaClientFactory is directly used for a specific client, this annotation can directly inject the corresponding client into the field annotated. In the above example, @SofaClientFactory is directly annotated on a ServiceClient field, and the SOFA framework directly injects the ServiceClient object into this field. You can obtain an object in this way if it exists in ClientFactory.

Programming API example

Service publication and subscription can be not only loaded statically on app startup by configuring a Spring Bean in the XML mode, but also executed dynamically by using the programming API at runtime, as follows:

Publish a Bolt service

ServiceClient serviceClient = clientFactory.getClient(ServiceClient.class);
ServiceParam serviceParam = new ServiceParam();
serviceParam.setInstance(sampleService);
serviceParam.setInterfaceType(SampleService.class);
serviceParam.setUniqueId(uniqueId);
TrBindingParam trBinding = new TrBindingParam();
// Correspond to the global-attrs tag.
trBinding.setClientTimeout(5000);
serviceParam.addBindingParam(trBinding);
serviceClient.service(serviceParam);

Reference a Bolt service

ReferenceClient referenceClient = clientFactory.getClient(ReferenceClient.class);
ReferenceParam<SampleService> referenceParam = new ReferenceParam<SampleService>();
referenceParam.setInterfaceType(SampleService.class);
referenceParam.setUniqueId(uniqueId);
TrBindingParam trBinding = new TrBindingParam();
// Correspond to the global-attrs tag.
trBinding.setClientTimeout(8000);
// Correspond to the method tag.
TrBindingMethodInfo trMethodInfo = new TrBindingMethodInfo();
trMethodInfo.setName("helloMethod");
trMethodInfo.setType("callback");
// The object must implement the com.alipay.sofa.rpc.api.callback.SofaResponseCallback interface.
trMethodInfo.setCallbackHandler(callbackHandler);
trBinding.addMethodInfo(trMethodInfo);
referenceParam.setBindingParam(trBinding);
SampleService proxy = referenceClient.reference(referenceParam);

Important:

• In SOFA, the Reference object created by dynamic client is heavy. Do not create it frequently in actual practice and make sure you cache it in advance. Otherwise, memory overflow may occur.
• The class of a programming API cannot be changed easily. To be compatible with previous usage, the class name still contains TR. However, the Bolt protocol is actually used.