Updated on 2025-07-03 GMT+08:00

Connecting Java Chassis Applications to CSE Engines

This section describes how to connect Java chassis applications to CSE engines and use the most common functions of CSE engines. For details about the development guide, see Using Microservice Engine Functions.

In the Apache ServiceComb Samples project, you can find the code corresponding to the development methods in this section.

Prerequisites

  • Microservice applications have been developed based on Java chassis.

    For details about microservice application development in the Java chassis framework, see https://servicecomb.apache.org/references/java-chassis/en_US/.

  • Version requirements. See Microservice Development Framework Versions.
  • This document assumes that you use Maven for dependency management and packaging in your project. You are familiar with the Maven dependency management mechanism and are able to modify the dependency management and dependency in the pom.xml file.
  • Java chassis can be used together with different technologies. The name of the configuration file is related to the technology you use. For example, if you use Java chassis in Spring mode, the configuration file name is microservice.yaml. If you use Java chassis in Spring Boot mode, the configuration file name is application.yaml. This document uses microservice.yaml to indicate the configuration file. You need to use a configuration file name corresponding to your project.

Procedure

  1. Add dependencies to the pom.xml file of the project.

    <dependency>
        <groupId>org.apache.servicecomb</groupId>
        <artifactId>solution-basic</artifactId>
    </dependency>
    <dependency>
        <groupId>org.apache.servicecomb</groupId>
        <artifactId>servicestage-environment</artifactId>
    </dependency>
    • The solution-basic module contains common Java chassis functions, such as the configuration center module and service governance module, which allow you to enable these functions in one-click.
      <!-- Configuration center module -->
      <dependency>
      <groupId>org.apache.servicecomb</groupId>
      <artifactId>config-cc</artifactId>
      </dependency>
      <!-- Service governance module -->
      <dependency>
      <groupId>org.apache.servicecomb</groupId>
      <artifactId>handler-governance</artifactId>
      </dependency>
    • The servicestage-environment module consists of the following dependent module:
      <!-- Registry and discovery module -->
      <dependency>
        <groupId>org.apache.servicecomb</groupId>
        <artifactId>registry-service-center</artifactId>
      </dependency>

    You are advised to use Maven Dependency Management to manage the third-party software dependencies of a project. Add the following information to the pom.xml file of the project:

    <dependencyManagement>
        <dependencies>
          <dependency>
            <groupId>org.apache.servicecomb</groupId>
            <artifactId>java-chassis-dependencies</artifactId>
            <version>${java-chassis.version}</version>
            <type>pom</type>
            <scope>import</scope>
          </dependency>
        </dependencies>  
    </dependencyManagement>

    Skip the operation if your project already contains the preceding dependencies.

    The servicestage-environment software package is optional. This software package provides the environment variable mapping function. When you use ServiceStage to deploy applications, you do not need to manually modify information such as the registry center address, configuration center address, and project name. The default configurations in the microservice.yaml file are overwritten by environment variables. The mapping.yaml file is contained in the software package. You can also add the mapping.yaml file to your own project.

    The mapping.yaml file may change in later versions to support the latest functions of CSE engines. If you do not want the new version to evolve with CSE engines, you can add the mapping.yaml file to your project instead of adding the servicestage-environment dependency.

    Generally, the microservice.yaml and mapping.yaml files are stored in the /src/main/resources/ directory in the root directory of the current project.

    PAAS_CSE_ENDPOINT:
      - servicecomb.service.registry.address
      - servicecomb.config.client.serverUri
    PAAS_CSE_SC_ENDPOINT:
      - servicecomb.service.registry.address
    PAAS_CSE_CC_ENDPOINT:
      - servicecomb.config.client.serverUri
    PAAS_PROJECT_NAME:
      - servicecomb.credentials.project
    
    # CAS_APPLICATION_NAME:
    #  - servicecomb.service.application
    # CAS_COMPONENT_NAME:
    #  - servicecomb.service.name
    # CAS_INSTANCE_VERSION:
    #  - servicecomb.service.version

    Common software packages are added to solution-basic, and the default microservice.yaml file is provided. This configuration file configures common Handlers and parameters as follows:

    # order of this configure file
    servicecomb-config-order: -100
    
    servicecomb:
    
    # handlers
      handler:
        chain:
          Provider:
            default: qps-flowcontrol-provider
          Consumer:
            default: qps-flowcontrol-consumer,loadbalance,fault-injection-consumer
    
    # loadbalance strategies
      references:
        version-rule: 0+
      loadbalance:
        retryEnabled: true
        retryOnNext: 1
        retryOnSame: 0
    
    # metrics and access log
      accesslog:
        enabled: true
      metrics:
        window_time: 60000
        invocation:
          latencyDistribution: 0,1,10,100,1000
        Consumer.invocation.slow:
          enabled: true
          msTime: 1000
        Provider.invocation.slow:
          enabled: true
          msTime: 1000
        publisher.defaultLog:
          enabled: true
          endpoints.client.detail.enabled: true

    servicecomb-config-order is set to -100 in the microservice.yaml configuration file, indicating that the priority of the configuration file is low. (A larger order indicates a higher priority. The default value is 0.) If the same configuration item is added to the service, the configuration will be overwritten.

    The microservice.yaml file may change in later versions to support the latest functions of CSE engines. If you do not want the new version to evolve with CSE engines, you can write the configuration items to your own microservice.yaml file.

  2. Configure microservice information.

    Add microservice configuration description to the microservice.yaml file. If there is no microservice.yaml file in the project, create one.

    servicecomb:
      service:
        application: porter-application
        name: user-service
        version: 0.0.1
        registry:
          address: http://localhost:30100
          instance:
            watch: true
            properties:
              key: value
            initialStatus: UP
      config:
        client:
          serverUri: http://localhost:30103
          fileSource: provider.yaml
          firstPullRequired: false
          refresh_interval: 15000
          domainName: default
      kie: 
        serverUri: http://127.0.0.1:30110
        domainName: default
        enableLongPolling: true
        pollingWaitTime: 10
        firstPullRequired: false
        customLabel: public 
        customLabelValue: default
    
    For the description of each configuration item, see Table 1.
    Table 1 Java chassis configuration items

    Item

    Description

    Default Value

    Mandatory

    Remarks

    servicecomb.service.application

    Name of the application to which the current microservice belongs.

    default

    Yes

    Only microservices with the same application name can discover each other.

    servicecomb.service.name

    Microservice name.

    -

    Yes

    -

    servicecomb.service.version

    Service version.

    1.0.0.0

    Yes

    This parameter is required during service upgrade to prevent contract registry failures.

    servicecomb.service.registry.address

    Registry address.

    -

    Yes

    -

    servicecomb.service.registry.instance.watch

    Whether to listen to microservice startup and shutdown.

    true

    No

    Use commas (,) to separate cluster addresses.

    servicecomb.service.registry.instance.properties

    Microservice instance property.

    -

    No

    The value is in the map structure. Multiple groups of data can be set.

    servicecomb.service.registry.instance.initialStatus

    Status when a microservice is registered.

    UP

    No

    Value: UP or DOWN.

    servicecomb.config.client.serverUri

    Access address. The format is http(s)://{ip}:{port}. Use commas (,) to separate multiple addresses.

    -

    Yes

    This configuration is applicable when the configuration center is config-center.

    • For microservice engine 1.x, {port} is 30103.
    • For microservice engine 2.x, {port} is 30110.

    servicecomb.config.client.fileSource

    List of YAML configuration items, which are separated by commas (,)

    -

    No

    When the configuration center type is config-center, if the configuration center delivers configurations through a configuration file, you must set fileSource to parse the configurations. Otherwise, the correct configurations cannot be obtained.

    servicecomb.config.client.firstPullRequired

    Whether the first pull configuration is forcibly successful. If the value is true, an exception is thrown after the first connection to the configuration center fails, and the service fails to be started. The default value is false.

    -

    No

    This configuration is applicable when the configuration center is config-center.

    servicecomb.config.client.refresh_interval

    Cycle time for config-center to obtain configurations, in milliseconds.

    15000

    No

    This configuration is applicable when the configuration center is config-center.

    servicecomb.config.client.domainName

    Project name.

    default

    No

    This configuration is applicable when the configuration center is config-center.

    servicecomb.kie.serverUri

    Access address. The format is http(s)://{ip}:{port}. Use commas (,) to separate multiple addresses.

    -

    Yes

    This configuration is applicable when the configuration center is kie.

    • For microservice engine 1.x, {port} is 30103.
    • For microservice engine 2.x, {port} is 30110.

    servicecomb.kie.domainName

    Project name.

    -

    No

    This configuration is applicable when the configuration center is kie.

    servicecomb.kie.enableLongPolling

    Whether to enable the long connection pull configuration.

    true

    No

    This configuration is applicable when the configuration center is kie.

    servicecomb.kie.pollingWaitTime

    Waiting duration of a long connection, in seconds.

    10

    No

    This configuration is applicable when the configuration center is kie.

    servicecomb.kie.firstPullRequired

    Whether the first pull configuration is forcibly successful. If the value is true, an exception is thrown after the first connection to the configuration center fails, and the service fails to be started. The default value is false.

    -

    No

    This configuration is applicable when the configuration center is kie.

    servicecomb.kie.customLabel

    Custom label.

    -

    No

    When the configuration center is kie, if a custom label is used to deliver configurations, you need to configure customLabel and customLabelValue. The microservice name, environment name, and application name labels support only independent adaptation.

    servicecomb.kie.customLabelValue

    Custom label value.

    -

    No

    -

  3. (Optional) Configure the AK/SK.

    If the professional microservice engine is used, you need to configure the AK/SK. For details, see Configuring the AK/SK for Java Chassis Microservice Applications Connected to the Professional Microservice Engine.

    If the exclusive microservice engine is used, you do not need to configure the AK/SK. In this case, skip this step.

    • Use environment variables. The OS environment variable name cannot contain periods (.). The Java chassis can automatically process the environment variable servicecomb_credentials_accessKey and map it to servicecomb.credentials.accessKey.
    • Add the mapping.yaml file and customize the environment variable name. For details about this method, see the servicestage-environment module in 1.

  4. (Optional) Configure security authentication parameters.

    Perform this step only when you use the exclusive microservice engine and enable security authentication. In other scenarios, skip this step.

    After security authentication is enabled for a microservice engine, all called APIs can be called only after a token is obtained. For details about the authentication process, see RBAC.

    To use security authentication, obtain the username and password from the microservice engine and then add the following configuration to the configuration file.

    servicecomb:
      credentials:
        rbac.enabled: true
        account:
          name: your account name # Username obtained from the microservice engine
          password: your password # Password obtained from the microservice engine
        cipher: default # Returned name of the name() method in the implementation class of API org.apache.servicecomb.foundation.auth.Cipher

    cipher specifies the name of the algorithm used to encrypt the password. By default, the password is stored in plaintext. The encryption is implemented through customization. The details are as follows:

    • Implement the org.apache.servicecomb.foundation.auth.Cipher API using either of the following methods:
      • String name()

        Name definition of servicecomb.credentials.cipher, which needs to be added to the configuration file.

      • char[] decode(char[] encrypted)

        Decrypt the API, which is used after secretKey is decrypted.

      The implementation class must be declared as SPI. For example:

      package com.example
      public class MyCipher implements Cipher

      Create an SPI configuration file. The file name and path are META-INF/service/org.apache.servicecomb.foundation.auth.Cipher, and the file content is as follows:

      com.example.MyCipher

      Add the following configuration to the microservice.yaml file:

      servicecomb:
        credentials:
          rbac.enabled: true
          account:
            name: your account name 
            password: your password # Encrypted password
          cipher: youciphername # Returned name of the name() method in the implementation class
    • Plaintext storage cannot ensure security. You are advised to encrypt the password.
    • You can also use environment variables to configure the username and password, which is the same as configuring the AK/SK. For details, see Configuring the AK/SK for Java Chassis Microservice Applications Connected to the Professional Microservice Engine.
    • If you use the professional microservice engine, the watch function is not available. You need to disable the watch function in the configuration file. Otherwise, error logs will be periodically printed. In the service center, set watch to false. In the configuration center, set refreshMode to 1.
      servicecomb:
        service:
          application: porter-application
          name: user-service
          version: 0.0.1
          registry:
            address: http://localhost:30100
            instance:
              watch: false
        config:
          client:
            serverUri: http://localhost:30103
            refreshMode: 1