Enterprise Distributed Application Service:API reference

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

The configuration and initialization of com.taobao.hsf.app.api.util.HSFApiProviderBean is required only once for a single service. We recommend that you cache the HSFApiProviderBean object because the object is complex.

• 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 implementation object of the operation that is specified by serviceInterface. hsfApiProviderBean.setServiceVersion("1.0.0");
  hsfApiProviderBean.setServiceGroup("HSF");
  
  // Initialize the provider bean for service publishing. 
  hsfApiProviderBean.init();

• Configurable properties

  In addition to the properties specified in the preceding sample code, HSFApiProviderBean includes other configurable properties. You can use the corresponding setter methods to configure these properties.

  Property	Type	Required	Default value	Description
  serviceInterface	String	Yes	N/A	The operation that is used to provide an HSF service. The consumer subscribes to the service by using this property.
  target	Object	Yes	N/A	The service implementation object of the operation that is specified by serviceInterface.
  serviceVersion	String	No	1.0.0	The version number of the service. The consumer subscribes to the service by using this property.
  serviceGroup	String	No	HSF	The group of the service. The consumer subscribes to the service by using this property.
  serviceDesc	String	No	null	The description of the service to facilitate management.
  clientTimeout	int	No	3000	The response timeout period. Unit: milliseconds. If the provider returns no response after the timeout period elapses, an HSFTimeOutException exception is thrown.
  methodSpecials	MethodSpecial[]	No	N/A	The response timeout period for specific methods in the service. Set the MethodSpecial.methodName parameter to a method name and set the MethodSpecial.clientTimout parameter to the timeout period for the current method. This property takes precedence over clientTimeout for the current provider.
  preferSerializeType	String	No	hessian2	The serialization method for the service request parameters and the service response result for HSF2. Valid values: java, hessian, hessian2, json, and kryo.
  corePoolSize	String whose value is an integer	No	0	The separate thread pool for the service, and the minimum number of active threads. By default, the public thread pool of the HSF provider is used if this property is not specified.
  maxPoolSize	String whose value is an integer	No	0	The separate thread pool for the service, and the maximum number of active threads. By default, the public thread pool of the HSF provider is used if this property is not specified.

To publish HSF services, you can configure a bean of the com.taobao.hsf.app.spring.util.HSFSpringProviderBean class 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] Specify the operation that is used to externally provide an HSF service. -->
    <property name="serviceInterface" value="com.taobao.hsf.test.HelloWorldService" />

    <!-- [Required] Specify the service implementation object of the operation that is specified by serviceInterface. To be specific, the object is identified by the Spring bean ID of the HSF service to be published. -->
    <property name="target" ref="helloWorldService" />

    <!-- [Optional] Specify the version number of the service. The default value is 1.0.0. -->
    <property name="serviceVersion" value="1.0.0" />

    <!-- [Optional] Specify the group to which the service belongs. The default value is HSF. -->
    <property name="serviceGroup" value="HSF" />

    <!-- [Optional] Specify the description of the service to facilitate management. The default value is null. -->
    <property name="serviceDesc" value="HelloWorldService providered by HSF" />

    <!-- [Optional] Specify the response timeout period. Unit: milliseconds. If the provider returns no response after the specified period elapses, an HSFTimeOutException exception is thrown. -->
    <!-- The default value is 3000. Unit: milliseconds. -->
    <property name="clientTimeout" value="3000"/>

    <!-- [Optional] Specify the response timeout period for specific methods in the service. This property takes precedence over clientTimeout. -->
    <!-- Set the MethodSpecial.methodName parameter to a method name and set the MethodSpecial.clientTimout parameter to the timeout period for the current method. -->
    <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] Specify the serialization method for the request parameters and the response result of the service. 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 specified. -->
    <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 specified. -->
    <property name="maxPoolSize" value="60"/>
</bean>

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

The configuration and initialization of com.taobao.hsf.app.api.util.HSFApiConsumerBean is required only once for a single service.

• 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.
  // A value of true indicates waiting for address push, with a timeout period of 3,000 ms. The default value is false, which indicates an asynchronous call.
  hsfApiConsumerBean.init(true);
  
  // Retrieve the HSF agent. 
  HelloWorldService helloWorldService = (HelloWorldService) hsfApiConsumerBean.getObject();
  
  // Initiate an HSF call. String 
  helloStr = helloWorldService.sayHello("Li Lei");

• Configurable properties

  In addition to the properties specified in the preceding sample code, HSFApiConsumerBean includes other configurable properties. You can use the corresponding setter methods to configure these properties.

  Property	Type	Required	Default value	Description
  interfaceName	String	Yes	N/A	The name of the operation for service subscription. The consumer subscribes to the service by using this property.
  version	String	Yes	N/A	The version number of the subscribed service. The consumer subscribes to the service by using this property.
  group	String	Yes	N/A	The group of the subscribed service. The consumer subscribes to the service by using this property.
  clientTimeout	int	No	N/A	The request timeout period. Unit: milliseconds. If the consumer receives no response from the provider after the timeout period elapses, an HSFTimeOutException exception is thrown. clientTimeout that is specified for the consumer takes precedence over clientTimeout that is specified for the provider. If clientTimeout is not specified for the consumer, clientTimeout that is specified for the provider is used during a remote service call.
  methodSpecials	MethodSpecial[]	No	N/A	The request timeout period for specific methods in the service. Set the MethodSpecial.methodName parameter to a method name and set the MethodSpecial.clientTimout parameter to the timeout period for the current method. This property takes precedence over clientTimeout for the current consumer.
  maxWaitTimeForCsAddress	int	No	N/A	The amount of time for the synchronous wait for Config Server to push an address. Unit: milliseconds. This property prevents an HSFAddressNotFoundException exception when the service is called before the address is pushed. We recommend that you set this property to 5000 to meet the requirement for wait time.
  asyncallMethods	List	No	null	A list of methods to be asynchronously called. Each string in the list is in the following format: name: the name of the method. type: the type of the asynchronous call. listener: the listener. In this list, the listener field takes effect only for asynchronous calls of the callback type. Valid values of the type field: future: The Future method is used to retrieve the request execution result. callback: After the remote service call is complete, HSF uses the response to call back the configured listener. This listener must implement HSFResponseCallback.
  proxyStyle	String	No	jdk	The agent mode of the service. Generally, this property does not need to be set. To block the consumer bean, set this property to javassist.

To subscribe to services, you can configure a bean of the com.taobao.hsf.app.api.util.HSFSpringConsumerBean class in the Spring profile.

Sample code

<bean id="helloWorldService" class="com.taobao.hsf.app.spring.util.HSFSpringConsumerBean">
    <!-- [Required] Specify the name of the operation for service subscription. -->
    <property name="interfaceName" value="com.taobao.hsf.test.HelloWorldService" />

    <!-- [Required] Specify the version number of the subscribed service. -->
    <property name="version" value="1.0.0" />

    <!-- [Required] Specify the group of the subscribed service. -->
    <property name="group" value="HSF" />

    <!-- [Optional] Specify the request timeout period. Unit: milliseconds. If the consumer receives no response from the provider after the timeout period elapses, an HSFTimeOutException exception is thrown. -->
    <!-- clientTimeout that is specified for the consumer takes precedence over clientTimeout that is specified for the provider. If clientTimeout is not specified for the consumer, clientTimeout that is specified for the provider is used during a remote service call. -->
    <property name="clientTimeout" value="3000" />

    <!-- [Optional] Specify the request timeout period for specific methods in the service. This property takes precedence over clientTimeout for the consumer. -->
    <!-- Set the MethodSpecial.methodName parameter to a method name and set the MethodSpecial.clientTimout parameter to the timeout period for the current method. -->
    <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] Specify the amount of time for the synchronous wait for Config Server to push an address. Unit: milliseconds. -->
    <!-- This prevents an HSFAddressNotFoundException exception when the service is called before the address is pushed. -->
    <!-- We recommend that you set this property to 5000 to meet the requirement for wait time. -->
    <property name="maxWaitTimeForCsAddress"  value="5000"/>

    <!-- [Optional] Specify a list of methods to be asynchronously called. Each string in the list is in the following format: -->
    <!-- name: the name of the method. -->
    <!-- type: the type of the asynchronous call. -->
    <!-- listener: the listener. -->
    <!-- The listener field takes effect only for asynchronous calls of the callback type.-->
    <!-- Valid values of the type field: -->
    <!-- future: The Future method is used to retrieve the request execution result. -->
    <!-- callback: After the remote service call is complete, HSF uses the response to call back the configured listener. This listener must implement HSFResponseCallback. -->
    <property name="asyncallMethods">
        <list>
            <value>name:sayHello;type:callback;listener:com.taobao.hsf.test.service.HelloWorldServiceCallbackHandler</value>
        </list>
    </property>

    <!-- [Optional] Specify the agent mode of the service. Generally, this property does not need to be set. To block the consumer bean, set this property to javassist. -->
    <property name="proxyStyle" value="jdk" />
</bean>