edit-icon download-icon

HSF development

Last Updated: Mar 12, 2018

EDAS now fully supports Spring Cloud applications, so you can directly deploy such applications in EDAS.

  • The concept of Spring Boot is to Build Anything to solve the problem of complicated XML configurations.
  • The concept of Spring Cloud is to Coordinate Anything to simplify the development of distributed microservices by providing strong spring-cloud-starter support for easy 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 demo source code: sc-hsf-provider, sc-hsf-consumer.

Preparations

Configure Maven private server

Currently, third-party packages of Spring Cloud for Aliware are only released in the private servers of EDAS, so the configuration of private server address is required. See Maven Documentation for instructions on how to configure Maven and Maven private server.

The address of private server is: http://edas-public.oss-cn-hangzhou.aliyuncs.com/repository

Note: Require Maven 3.x or later. Add the EDAS private server address in Maven configuration file settings. Download a sample file.

Lightweight Configuration Center

The Lightweight Configuration Center must be started for local development and debugging. It includes a lightweight version of the EDAS service discovery and configuration management feature. See Lightweight Configuration Center for details.

Example: A simple HSF application

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.1</version>
    12. </dependency>
    13. <dependency>
    14. <groupId>org.springframework.cloud</groupId>
    15. <artifactId>spring-cloud-starter-pandora</artifactId>
    16. <version>1.2</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 lifecycle 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 property 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 practice: 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 for loading the Pandora container.
    5. PandoraBootstrap.run(args);
    6. SpringApplication.run(ServerApplication.class, args);
    7. // Mark that the service startup is completed, and set the thread to wait to prevent the container from exiting after the user's business code is run.
    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.1</version>
    12. </dependency>
    13. <dependency>
    14. <groupId>org.springframework.cloud</groupId>
    15. <artifactId>spring-cloud-starter-pandora</artifactId>
    16. <version>1.2</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 pulished 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 using annotations.

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

    Best practice: 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 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 practice: 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 debugging

Start the Lightweight Configuration Center

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

Start the application

The application can be started locally in two ways.

Start in IDE

Configure the startup parameter -Djmenv.tbsite.net={$IP} in VM options, and start the application directly using the main method. {$IP} is the address of the machine on which the Lightweight Configuration Center service is started. For example, if it 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 of the machine on which the Lightweight Configuration Center service is started. For details, see Lightweight Configuration Center.

Start 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 build plugin.

    1. <build>
    2. <plugin>
    3. <groupId>com.taobao.pandora</groupId>
    4. <artifactId>pandora-boot-maven-plugin</artifactId>
    5. <version>2.1.7.8</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, and 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.

Demo

Start the service and make a call, and you can see that the call is successful.

HSF demo

Deploy in EDAS

  1. Select a container of the latest version when creating an application.
  2. Add FatJar packaging plugins, and run the mvn clean package command under the directory of the project to create a FatJar package.
  3. Deploy the application. The application can be deployed in EDAS by uploading the FatJar application under the target directory.
Thank you! We've received your feedback.