Background information

High-Speed Service Framework (HSF) provides user-oriented interfaces to create provider beans and consumer beans. There are four interface classes based on use cases.
  • com.taobao.hsf.app.api.util.HSFApiProviderBean: creates provider beans through API programming.
  • com.taobao.hsf.app.api.util.HSFApiConsumerBean: creates consumer beans through API programming.
  • com.taobao.hsf.app.spring.util.HSFSpringProviderBean: creates provider beans through Spring configuration.
  • com.taobao.hsf.app.spring.util.HSFSpringConsumerBean: creates consumer beans through Spring configuration.

The configuration property of HSFSpringXxxBean corresponds to the setter method of HSFApiXxxBean. The following describes how to create provider beans and consumer beans by using the four interface classes.

Provider bean

  • API programming - HSFApiProviderBean

    You can publish HSF services by configuring and initializing com.taobao.hsf.app.api.util.HSFApiProviderBean.

    The configuration and initialization process is implemented only once for publishing a service. We recommend that you cache the HSFApiProviderBean object due to its large size.

    • Sample code:
      // Instantiate and configure a provider bean.
      HSFApiProviderBean hsfApiProviderBean = new HSFApiProviderBean();
      hsfApiProviderBean.setServiceInterface("com.taobao.hsf.test.HelloWorldService");
      hsfApiProviderBean.setTarget(target); // target indicates the object that is implemented by the interface designated by serviceInterface.
      hsfApiProviderBean.setServiceVersion("1.0.0");
      hsfApiProviderBean.setServiceGroup("HSF");
      
      // Initialize the provider bean for service publishing.
      hsfApiProviderBean.init();
    • Configurable properties:

      You can use the setter method to set the properties of HSFApiProviderBean, including the properties displayed in the sample code.

      Property Type Required Default value Description
      serviceInterface String Yes None Specifies the interface used to externally publish an HSF service. The consumer subscribes to the service through this property.
      target Object Yes None Specifies the service that is provided through the interface designated by serviceInterface.
      serviceVersion String No 1.0.0 Specifies the version of the service. The consumer subscribes to the service through this property.
      serviceGroup String No HSF Specifies the group to which the service belongs. The consumer subscribes to the service through this property.
      serviceDesc String No null Specifies the description of the service for easy management.
      clientTimeout int No 3000 Specifies the response time-out period, in ms. HSFTimeOutException is thrown if the provider returns no response within the time-out period.
      methodSpecials MethodSpecial[] No N/A Specifies the response time-out period for some methods in the service. You can specify a method name through MethodSpecial.methodName and specify a time-out period for the method through MethodSpecial.clientTimout. This property takes precedence over clientTimeout for the provider.
      preferSerializeType String No hessian2 Specifies the serialization method for the service request parameters and response for HSF2. Valid values: java, hessian, hessian2, json, and kryo.
      corePoolSize String whose value is an integer No 0 Configures a separate thread pool for the service and specifies the minimum number of active threads. By default, the public thread pool of the HSF provider is used if this property is not set.
      maxPoolSize String whose value is an integer No 0 Configures a separate thread pool for the service and specifies the maximum number of active threads. By default, the public thread pool of the HSF provider is used if this property is not set.
  • Spring configuration - HSFSpringProviderBean

    You can publish HSF services by configuring a bean of the class com.taobao.hsf.app.spring.util.HSFSpringProviderBean in the Spring profile.

    Sample code

    <bean id="helloWorldService" class="com.taobao.hsf.test.HelloWorldService" />
    
    <bean class="com.taobao.hsf.app.spring.util.HSFSpringProviderBean" init-method="init">
        <! -- [Required] Set the interface used to externally provide an HSF service. -->
        <property name="serviceInterface" value="com.taobao.hsf.test.HelloWorldService" />
    
        <! -- [Required] Set the service that is provided by the interface designated by serviceInterface, that is, the Spring bean ID of the HSF service to be published. -->
        <property name="target" ref="helloWorldService" />
    
        <! -- [Optional] Set the version of the service. The default value is 1.0.0. -->
        <property name="serviceVersion" value="1.0.0" />
    
        <! -- [Required] Set the group to which the service belongs. The default value is HSF. -->
        <property name="serviceGroup" value="HSF" />
    
        <! -- [Required] Set the description of the service. The default value is null. -->
        <property name="serviceDesc" value="HelloWorldService providered by HSF" />
    
        <! -- [Required] Set the response time-out period, in ms. HSFTimeOutException is thrown if the provider returns no response within the time-out period. -->
        <! -- The default value is 3000 ms. -->
        <property name="clientTimeout" value="3000"/>
    
        <! -- [Required] Set the response time-out period for some methods in the service. This property takes precedence over clientTimeout. -->
        <! -- Specify a method name through MethodSpecial.methodName and specify a time-out period for the method through MethodSpecial.clientTimout. -->
        <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] Set the serialization method for the service request parameters and response. Valid values: java, hessian, hessian2, json, and kryo. -->
        <! -- The default value is hessian2. -->
        <property name="preferSerializeType" value="hessian2"/>
    
        <! -- [Optional] Configure a separate thread pool for the service and specify the minimum number of active threads. By default, the public thread pool of the HSF provider is used if this property is not set. -->
        <property name="corePoolSize" value="10"/>
    
        <! -- [Optional] Configure a separate thread pool for the service and specify the maximum number of active threads. By default, the public thread pool of the HSF provider is used if this property is not set. -->
        <property name="maxPoolSize" value="60"/>
    </bean>

Consumer bean

  • API programming - HSFApiConsumerBean

    You can subscribe to HSF services by configuring and initializing com.taobao.hsf.app.api.util.HSFApiConsumerBean.

    The com.taobao.hsf.app.api.util.HSFApiConsumerBean configuration and initialization process is implemented only once for the same service.

    We recommend that you cache the HSFApiConsumerBean object and the retrieved HSF proxy because the object content is large.
    Note In the HSF, HSFApiConsumerBean caches service configuration. If a subscribed service is configured multiple times, only the first configuration takes effect.
    • Sample code
      // 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 for service subscription.
      // true indicates waiting for address push (time-out period: 3,000 ms). The default value is false, which indicates an asynchronous call.
      hsfApiConsumerBean.init(true);
      
      // Retrieve the HSF proxy.
      HelloWorldService helloWorldService = (HelloWorldService) hsfApiConsumerBean.getObject();
      
      // Initiate an HSF call.
      String helloStr = helloWorldService.sayHello("Li Lei");
    • Configurable properties

      You can use the setter method to set the properties of HSFApiConsumerBean, including the properties displayed in the sample code.

      Property Type Required Default value Description
      interfaceName String Yes None Specifies the interface for service subscription. The consumer subscribes to the service through this property.
      version String Yes None Specifies the version of the subscribed service. The consumer subscribes to the service through this property.
      group String Yes None Specifies the group to which the subscribed service belongs. The consumer subscribes to the service through this property.
      clientTimeout int No None Specifies the request time-out period, in ms. HSFTimeOutException is thrown if the consumer receives no response from the provider. clientTimeout set for the consumer takes precedence over that set for the provider. If clientTimeout is not set for the consumer, clientTimeout set for the provider is used during remote service call.
      methodSpecials MethodSpecial[] No N/A Specifies the request time-out period for some methods in the service. You can specify a method name through MethodSpecial.methodName and specify a time-out period for the method through MethodSpecial.clientTimout. This property takes precedence over clientTimeout for the consumer.
      maxWaitTimeForCsAddress int No None Specifies the time for the synchronous wait for Config Server to push an address (unit: ms) to avoid HSFAddressNotFoundException that may occur when the service is called before any address is pushed. We recommend that you set this property to 5,000 ms.
      asyncallMethods List No null Specifies a list of methods to be called asynchronously. Each string in List is in the format name;type;listener. "type" indicates the type of asynchronous call. "listener" takes effect only for asynchronous call of the callback type. "type" can be set to "future" or "callback". When it is set to "future", the request implementation result is retrieved by using the Future method. When it is set to "callback", the HSF application uses the response to call back the configured listener, which must implement HSFResponseCallback.
      proxyStyle String No jdk Specifies the proxy mode of the service. Do not set this property unless necessary. To block the consumer bean, set this property to javassist.
  • Spring configuration - HSFSpringConsumerBean

    You can subscribe to services by configuring a bean of the class com.taobao.hsf.app.api.util.HSFSpringConsumerBean in the Spring profile.

    Sample code

    <bean id="helloWorldService" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
        <! -- [Required] Set the interface for service subscription. -->
        <property name="interfaceName" value="com.taobao.hsf.test.HelloWorldService" />
    
        <! -- [Required] Set the version of the subscribed service. -->
        <property name="version" value="1.0.0" />
    
        <! -- [Required] Set the group to which the subscribed service belongs. -->
        <property name="group" value="HSF" />
    
        <! -- [Required] Set the request time-out period, in ms. HSFTimeOutException is thrown if the consumer receives no response from the provider. -->
        <! -- clientTimeout set for the consumer takes precedence over that set for the provider. If clientTimeout is not set for the consumer, clientTimeout set for the provider is used during remote service call.-->
        <property name="clientTimeout" value="3000" />
    
        <! -- [Optional] Set the request time-out period for some methods in the service. This property takes precedence over clientTimeout for the consumer. -->
        <! -- Specify a method name through MethodSpecial.methodName and specify a time-out period for the method through MethodSpecial.clientTimout. -->
        <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] Set the time (unit: ms) to synchronously wait for Config Server to push an address. -->
        <! -- This avoids HSFAddressNotFoundException that may occur when the service is called before any address is pushed. -->
        <! -- We recommend that you set this property to 5,000 ms. -->
        <property name="maxWaitTimeForCsAddress"  value="5000"/>
    
        <! -- [Optional] Set a list of methods to be called asynchronously. Each string in List is in the format name;type;listener. "type" indicates the type of asynchronous call.
        <! -- "listener" takes effect only for asynchronous call of the callback type. "type" can be set to:-->
        <! -- future: The request implementation result is retrieved by using the Future method. -->
        <! -- callback: HSF uses the response to call back the configured listener, which must implement HSFResponseCallback. -->
        <property name="asyncallMethods">
            <list>
                <value>name:sayHello;type:callback;listener:com.taobao.hsf.test.service.HelloWorldServiceCallbackHandler</value>
            </list>
        </property>
    
        <! -- [Optional] Set the proxy mode of the service. Do not set this property unless necessary. To block the consumer bean, set this property to javassist. -->
        <property name="proxyStyle" value="jdk" />
    </bean>