edit-icon download-icon

HSF development

Last Updated: Nov 16, 2018

Currently, EDAS fully supports Spring Cloud applications and they can be deployed directly in EDAS.

  • The concept behind Spring Boot is to Build Anything, helping resolve complicated XML configuration problems.
  • The concept behind Spring Cloud is to Coordinate Anything, helping simplify the development of distributed microservices by providing a large number of spring-cloud-starters, which are convenient for component access.

EDAS also implements its own Spring Cloud Starter HSF, allowing you to develop HSF applications using Spring Cloud.

This topic describes how to use Spring Cloud to develop HSF applications.

Download the Demo source code sc-hsf-provider and sc-hsf-consumer.

Create a service provider

  1. Create a Spring Cloud project named sc-hsf-provider.

  2. Introduce necessary dependencies in pom.xml:

    1. <parent>
    2. <groupId>org.springframework.boot</groupId>
    3. <artifactId>spring-boot-starter-parent</artifactId>
    4. <version>1.5.8.RELEASE</version>
    5. <relativePath/>
    6. </parent>
    7. <dependencies>
    8. <dependency>
    9. <groupId>org.springframework.cloud</groupId>
    10. <artifactId>spring-cloud-starter-hsf</artifactId>
    11. <version>1.3</version>
    12. </dependency>
    13. <dependency>
    14. <groupId>org.springframework.cloud</groupId>
    15. <artifactId>spring-cloud-starter-pandora</artifactId>
    16. <version>1.3</version>
    17. </dependency>
    18. <dependency>
    19. <groupId>org.springframework.boot</groupId>
    20. <artifactId>spring-boot-starter-web</artifactId>
    21. </dependency>
    22. </dependencies>
    23. <dependencyManagement>
    24. <dependencies>
    25. <dependency>
    26. <groupId>org.springframework.cloud</groupId>
    27. <artifactId>spring-cloud-dependencies</artifactId>
    28. <version>Dalston.SR4</version>
    29. <type>pom</type>
    30. <scope>import</scope>
    31. </dependency>
    32. </dependencies>
    33. </dependencyManagement>

    Although the HSF service framework does not rely on the Web environment, web-related features are required when EDAS is used to manage the life cycle of applications. Therefore, a dependency for spring-boot-starter-web must be added.

    If you do not want to configure the parent of the project as spring-boot-starter-parent, you can add dependencyManagement and set scope=import as follows to manage dependency versions.

    1. <dependencyManagement>
    2. <dependencies>
    3. <dependency>
    4. <groupId>org.springframework.boot</groupId>
    5. <artifactId>spring-boot-dependencies</artifactId>
    6. <version>1.5.8.RELEASE</version>
    7. <type>pom</type>
    8. <scope>import</scope>
    9. </dependency>
    10. </dependencies>
    11. </dependencyManagement>
  3. Define a service API, and create an API class of com.aliware.edas.EchoService.

    1. public interface EchoService {
    2. String echo(String string);
    3. }

    The HSF service framework enables service communication based on APIs. When an API is defined, producers implement and release specific services using this API, and consumers subscribe and consume services also using this API.

    The API com.aliware.edas.EchoService provides an echo method, which also means that the service com.aliware.edas.EchoService provides an echo method.

  4. Add the implementation class EchoServiceImpl of the service provider, and publish the service using annotations.

    1. @HSFProvider(serviceInterface = EchoService.class, serviceVersion = "1.0.0")
    2. public class EchoServiceImpl implements EchoService {
    3. @Override
    4. public String echo(String string) {
    5. return string;
    6. }
    7. }

    In addition to the API name serviceInterface, HSF also requires serviceVersion (service version) to uniquely identify a service. In this case, the serviceVersion attribute in the HSFProvider annotation is set to “1.0.0”. Then, the service to be published can be identified by the combination of serviceInterface com.aliware.edas.EchoService and serviceVersion 1.0.0.

    The configuration in the HSFProvider annotation has the highest priority. If it is not configured in the HSFProvider annotation, the global configuration of these properties is checked in the file resources/application. properties when the service is published.If neither is configured, the default values in the HSFProvider annotation are used.

  5. Configure the application name and the listener port number in the application.properties file in resources.

    1. spring.application.name=hsf-provider
    2. server.port=18081
    3. spring.hsf.version=1.0.0
    4. spring.hsf.timeout=3000

    Best practices: We recommend that you configure both service version and service time-out in application.properties.

  6. Add main function entrance for starting the service.

    1. @SpringBootApplication
    2. public class HSFProviderApplication {
    3. public static void main(String[] args) {
    4. // Start Pandora Boot to load the Pandora container
    5. PandoraBootstrap.run(args);
    6. SpringApplication.run(ServerApplication.class, args);
    7. // It indicates that the service is started, and the thread wait time is set. It can prevent the container from exiting due to users' exiting after running the business code.
    8. PandoraBootstrap.markStartupAndWait();
    9. }
    10. }

Create a service consumer

In this example, we create a service consumer that calls the service provider using the API provided by HSFProvider.

  1. Create a Spring Cloud project named sc-hsf-consumer.

  2. Introduce necessary dependencies in pom.xml:

    The Maven dependencies for HSFConsumer and HSFProvider are exactly the same.

    1. <parent>
    2. <groupId>org.springframework.boot</groupId>
    3. <artifactId>spring-boot-starter-parent</artifactId>
    4. <version>1.5.8.RELEASE</version>
    5. <relativePath/>
    6. </parent>
    7. <dependencies>
    8. <dependency>
    9. <groupId>org.springframework.cloud</groupId>
    10. <artifactId>spring-cloud-starter-hsf</artifactId>
    11. <version>1.3</version>
    12. </dependency>
    13. <dependency>
    14. <groupId>org.springframework.cloud</groupId>
    15. <artifactId>spring-cloud-starter-pandora</artifactId>
    16. <version>1.3</version>
    17. </dependency>
    18. <dependency>
    19. <groupId>org.springframework.boot</groupId>
    20. <artifactId>spring-boot-starter-web</artifactId>
    21. </dependency>
    22. </dependencies>
    23. <dependencyManagement>
    24. <dependencies>
    25. <dependency>
    26. <groupId>org.springframework.cloud</groupId>
    27. <artifactId>spring-cloud-dependencies</artifactId>
    28. <version>Dalston.SR4</version>
    29. <type>pom</type>
    30. <scope>import</scope>
    31. </dependency>
    32. </dependencies>
    33. </dependencyManagement>
  3. Copy the service API (including the package name) com.aliware.edas.EchoService published by the service provider to a local machine.

    1. public interface EchoService {
    2. String echo(String string);
    3. }
  4. Inject the instance of the service consumer into the Context of Spring by using annotations.

    1. @Configuration
    2. public class HsfConfig {
    3. @HSFConsumer(clientTimeout = 3000, serviceVersion = "1.0.0")
    4. private EchoService echoService;
    5. }

    Best practices: Configure @HSFConsumer once in the Config class, and inject and use it in multiple places through @Autowired.Usually, an HSF Consumer is used in multiple places, but you do not have to mark each place where it is used with @HSFConsumer.You can write a unified Config class and inject it directly wherever it is needed through @Autowired.

  5. For ease of test, an HTTP API of /hsf-echo/* is exposed with SimpleController. Calling the HSF service provider is internally implemented in the API /hsf-echo/*.

    1. @RestController
    2. public class SimpleController {
    3. @Autowired
    4. private EchoService echoService;
    5. @RequestMapping(value = "/hsf-echo/{str}", method = RequestMethod.GET)
    6. public String echo(@PathVariable String str) {
    7. return echoService.echo(str);
    8. }
    9. }
  6. Configure the application name and the listener port number in the application.properties file in resources.

    1. spring.application.name=hsf-consumer
    2. server.port=18082
    3. spring.hsf.version=1.0.0
    4. spring.hsf.timeout=1000

    Best practices: We recommend that you configure both service version and service time-out in application.properties.

  7. Add main function entrance for starting the service.

    1. @SpringBootApplication
    2. public class HSFConsumerApplication {
    3. public static void main(String[] args) {
    4. PandoraBootstrap.run(args);
    5. SpringApplication.run(HSFConsumerApplication.class, args);
    6. PandoraBootstrap.markStartupAndWait();
    7. }
    8. }

Local development and commissioning

Start the Lightweight Configuration Center

The Lightweight Configuration Center must be started for local development and commissioning, which includes a lightweight version of the server of EDAS service registration and discovery. See Lightweight Configuration Center for details.

Start the application

The application can be locally started in two ways.

Start in IDE

Configure the startup parameter -Djmenv.tbsite.net=$IP in VM options, and start the application directly by using the main method. $IP is the address of the machine on which the Lightweight Configuration Center is started. For example, if the center is started on the current machine, $IP is 127.0.0.1.

Instead of configuring JVM parameters, you can also directly modify the hosts file to bind jmenv.tbsite.net to the IP address of the machine on which the Lightweight Configuration Center is started. See Lightweight Configuration Center for details.

Start by using FatJar

  1. Add FatJar packaging plugins.

    To package pandora-boot project into FatJar by using Maven, the following plugins should be added in pom.xml.

    To avoid conflicts with other packaging plugins, do not add other FatJar plugins in the build plugin.

    1. <build>
    2. <plugin>
    3. <groupId>com.taobao.pandora</groupId>
    4. <artifactId>pandora-boot-maven-plugin</artifactId>
    5. <version>2.1.9.1</version>
    6. <executions>
    7. <execution>
    8. <phase>package</phase>
    9. <goals>
    10. <goal>repackage</goal>
    11. </goals>
    12. </execution>
    13. </executions>
    14. </plugin>
    15. </build>
  2. After adding the plugins, run the maven command mvn clean package under the home directory of the project to create a package. The created FatJar file is located under the target directory.

  3. Start the application using Java command.

    1. java -Djmenv.tbsite.net=127.0.0.1 -Dpandora.location=/Users/{$username}/.m2/repository/com/taobao/pandora/taobao-hsf.sar/dev-SNAPSHOT/taobao-hsf.sar-dev-SNAPSHOT.jar -jar sc-hsf-provider-0.0.1-SNAPSHOT.jar

    NOTE: The path specified by -Dpandora.location must be a full path placed before sc-hsf-provider-0.0.1-SNAPSHOT.jar.

Demonstration

Enable the service and check whether it can be called.

Basic HSF demonstration

Thank you! We've received your feedback.