Publish & Subscribe to HSF Services via Java API for Microservice Communication - EDAS

HSF provides four classes for publishing and subscribing to services. Each class is available as either a Java API or a Spring XML configuration.

Class	Role	Approach
`HSFApiProviderBean`	Publish a service	Java API
`HSFSpringProviderBean`	Publish a service	Spring XML
`HSFApiConsumerBean`	Subscribe to a service	Java API
`HSFSpringConsumerBean`	Subscribe to a service	Spring XML

Each Spring class (HSFSpringXxxBean) exposes the same configuration as the setter methods on its corresponding API class (HSFApiXxxBean).

Prerequisites

Before you begin, make sure that you have:

The EDAS SDK added as a Maven dependency (see Add the dependency)
A service interface and its implementation class

Add the dependency

Add the following dependency to your pom.xml file:

<dependency>
    <groupId>com.alibaba.edas</groupId>
    <artifactId>edas-sdk</artifactId>
    <version>{version}</version>
</dependency>

Replace {version} with your EDAS SDK version.

Publish a service (ProviderBean)

A provider bean publishes a service interface implementation to the HSF registry so that consumers can discover and call it.

Important

Initialize each HSFApiProviderBean only once per service. Cache the object after initialization -- creating it is resource-intensive.

Java API approach

Use com.taobao.hsf.app.api.util.HSFApiProviderBean to publish a service programmatically.

// Instantiate and configure a provider bean.
HSFApiProviderBean hsfApiProviderBean = new HSFApiProviderBean();
hsfApiProviderBean.setServiceInterface("com.taobao.hsf.test.HelloWorldService");
hsfApiProviderBean.setTarget(target); // target is the implementation object of the interface specified by serviceInterface.
hsfApiProviderBean.setServiceVersion("1.0.0");
hsfApiProviderBean.setServiceGroup("HSF");

// Initialize the provider bean to publish the service.
hsfApiProviderBean.init();

Spring XML approach

Use com.taobao.hsf.app.spring.util.HSFSpringProviderBean in a Spring configuration file to publish a service declaratively.

<bean id="helloWorldService" class="com.taobao.hsf.test.HelloWorldService" />

<bean class="com.taobao.hsf.app.spring.util.HSFSpringProviderBean" init-method="init">
    <!-- [Required] Service interface -->
    <property name="serviceInterface" value="com.taobao.hsf.test.HelloWorldService" />

    <!-- [Required] Implementation object (Spring bean ID) -->
    <property name="target" ref="helloWorldService" />

    <!-- [Optional] Service version. Default: 1.0.0 -->
    <property name="serviceVersion" value="1.0.0" />

    <!-- [Optional] Service group. Default: HSF -->
    <property name="serviceGroup" value="HSF" />

    <!-- [Optional] Service description -->
    <property name="serviceDesc" value="HelloWorldService providered by HSF" />

    <!-- [Optional] Response timeout in milliseconds. Default: 3000 -->
    <property name="clientTimeout" value="3000"/>

    <!-- [Optional] Per-method timeout. Takes precedence over clientTimeout. -->
    <property name="methodSpecials">
        <list>
            <bean class="com.taobao.hsf.model.metadata.MethodSpecial">
                <property name="methodName" value="sum" />
                <property name="clientTimeout" value="2000" />
            </bean>
        </list>
    </property>

    <!-- [Optional] Serialization method. Valid values: java, hessian, hessian2, json, kryo. Default: hessian2 -->
    <property name="preferSerializeType" value="hessian2"/>

    <!-- [Optional] Minimum threads in a dedicated thread pool. Default: shared HSF thread pool -->
    <property name="corePoolSize" value="10"/>

    <!-- [Optional] Maximum threads in a dedicated thread pool. Default: shared HSF thread pool -->
    <property name="maxPoolSize" value="60"/>
</bean>

ProviderBean properties

Property	Type	Required	Default	Description
serviceInterface	String	Yes	N/A	The interface that provides the HSF service. Consumers use this interface to subscribe.
target	Object	Yes	N/A	The implementation object of the interface specified by serviceInterface.
serviceVersion	String	No	1.0.0	Service version. Consumers use this value to subscribe to a specific version.
serviceGroup	String	No	HSF	Service group. Consumers use this value to subscribe to a specific group.
serviceDesc	String	No	N/A	Description of the service for management purposes.
clientTimeout	int	No	3000	Response timeout in milliseconds. Throws `HSFTimeOutException` if the provider does not respond in time.
methodSpecials	MethodSpecial[]	No	N/A	Per-method timeout overrides. Set `MethodSpecial.methodName` to the method name and `MethodSpecial.clientTimout` to the timeout value in milliseconds. Takes precedence over clientTimeout.
preferSerializeType	String	No	hessian2	Serialization protocol for request and response data. Valid values: `java`, `hessian`, `hessian2`, `json`, `kryo`.
corePoolSize	String (integer value)	No	0	Minimum threads in a dedicated thread pool for this service. When unset, the shared HSF provider thread pool is used.
maxPoolSize	String (integer value)	No	0	Maximum threads in a dedicated thread pool for this service. When unset, the shared HSF provider thread pool is used.

Subscribe to a service (ConsumerBean)

A consumer bean subscribes to a published HSF service and provides a proxy object for remote invocation.

Important

Initialize each HSFApiConsumerBean only once per service. Cache both the bean object and the proxy it returns -- creating them is resource-intensive.

Warning

HSFApiConsumerBean caches service configurations internally. If you configure the same service multiple times, only the first configuration takes effect.

Java API approach

Use com.taobao.hsf.app.api.util.HSFApiConsumerBean to subscribe to a service programmatically.

// Instantiate and configure a consumer bean.
HSFApiConsumerBean hsfApiConsumerBean = new HSFApiConsumerBean();
hsfApiConsumerBean.setInterfaceName("com.taobao.hsf.test.HelloWorldService");
hsfApiConsumerBean.setVersion("1.0.0");
hsfApiConsumerBean.setGroup("HSF");

// Initialize the consumer bean.
// true = wait synchronously for address push (timeout: 3000 ms).
// false (default) = initialize asynchronously.
hsfApiConsumerBean.init(true);

// Get the HSF proxy object.
HelloWorldService helloWorldService = (HelloWorldService) hsfApiConsumerBean.getObject();

// Call the remote service.
String helloStr = helloWorldService.sayHello("Li Lei");

Spring XML approach

Use com.taobao.hsf.app.spring.util.HSFSpringConsumerBean in a Spring configuration file to subscribe to a service declaratively.

<bean id="helloWorldService" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
    <!-- [Required] Service interface name -->
    <property name="interfaceName" value="com.taobao.hsf.test.HelloWorldService" />

    <!-- [Required] Service version -->
    <property name="version" value="1.0.0" />

    <!-- [Required] Service group -->
    <property name="group" value="HSF" />

    <!-- [Optional] Request timeout in milliseconds. Consumer timeout takes precedence over provider timeout. -->
    <property name="clientTimeout" value="3000" />

    <!-- [Optional] Per-method timeout. Takes precedence over clientTimeout. -->
    <property name="methodSpecials">
        <list>
            <bean class="com.taobao.hsf.model.metadata.MethodSpecial">
                <property name="methodName" value="sum" />
                <property name="clientTimeout" value="2000" />
            </bean>
        </list>
    </property>

    <!-- [Optional] Synchronous wait time (ms) for Config Server to push a service address.
         Prevents HSFAddressNotFoundException when the service is called before the address arrives.
         Recommended: 5000 -->
    <property name="maxWaitTimeForCsAddress" value="5000"/>

    <!-- [Optional] Async call methods. Format: name:<method>;type:<future|callback>;listener:<class>
         The listener field only applies to the callback type and must implement HSFResponseCallback. -->
    <property name="asyncallMethods">
        <list>
            <value>name:sayHello;type:callback;listener:com.taobao.hsf.test.service.HelloWorldServiceCallbackHandler</value>
        </list>
    </property>

    <!-- [Optional] Proxy mode. Default: jdk. Set to javassist to block the consumer bean. -->
    <property name="proxyStyle" value="jdk" />
</bean>

ConsumerBean properties

Property	Type	Required	Default	Description
interfaceName	String	Yes	N/A	The interface name to subscribe to.
version	String	Yes	N/A	The version of the target service.
group	String	Yes	N/A	The group of the target service.
clientTimeout	int	No	N/A	Request timeout in milliseconds. Throws `HSFTimeOutException` if no response is received. Consumer timeout takes precedence over provider timeout. When unset, the provider timeout applies.
methodSpecials	MethodSpecial[]	No	N/A	Per-method timeout overrides. Set `MethodSpecial.methodName` to the method name and `MethodSpecial.clientTimout` to the timeout value in milliseconds. Takes precedence over clientTimeout.
maxWaitTimeForCsAddress	int	No	N/A	Milliseconds to wait synchronously for Config Server to push a service address. Prevents `HSFAddressNotFoundException` when the service is called before the address arrives. Recommended: 5000.
asyncallMethods	List	No	N/A	Methods to call asynchronously. Each entry uses the format `name:<method>;type:<type>;listener:<class>`. Valid types: `future` (retrieve the result with a Future object) and `callback` (HSF invokes the listener after the call completes). The `listener` field applies only to the `callback` type and must implement `HSFResponseCallback`.
proxyStyle	String	No	jdk	Proxy mode. Set to `javassist` to block the consumer bean.

Async call patterns

HSF supports two async call patterns for consumer methods, configured through the asyncallMethods property:

Pattern	How it works
`future`	Returns immediately. Retrieve the result later with a `Future` object.
`callback`	Returns immediately. HSF invokes the registered listener when the response arrives. The listener must implement `HSFResponseCallback`.