This project is the source code of the Tars RPC framework Java language.
| Homepage: | tarscloud.org |
| 中文版: | 点我查看中文版 |
- JDK1.8 or above
- Maven 3.5 or above
This guide uses Docker to complete the deployment of Tars.[Macos、 Linux]
** Start TarsFramework in Docker**
docker pull tarscloud/framework:latest
docker pull tarscloud/tars-node:latest
docker pull mysql:5.6
docker network create -d bridge --subnet=172.25.0.0/16 --gateway=172.25.0.1 tars
docker run -d \
--net=tars \
-e MYSQL_ROOT_PASSWORD="root@appinside" \
--ip="172.25.0.2" \
--name=tars-mysql \
mysql:5.6
sleep 30s
docker run -d \
--net=tars \
-e MYSQL_HOST=172.25.0.2 \
-e MYSQL_ROOT_PASSWORD='root@appinside' \
-eREBUILD=false -eSLAVE=false \
-e INET=eth0 \
--ip="172.25.0.4" \
-p 3000-3001:3000-3001 \
tarscloud/framework
sleep 60s
docker run -d --net=tars --ip="172.25.0.3" -eWEB_HOST=http://172.25.0.4:3000 tarscloud/tars-nodeNote: - P 18600-18700:18600-18700 parameter opens 18600-18700 port for application. You can add more ports if necessary
This guide gives you a quick introduction to Tars in Java through simple server example server
├── pom.xml
└── src
└── main
├── java
│ └── tars
│ └── testapp
│ ├── HelloServant.java
│ ├── QuickStartApplication.java
│ └── impl
│ └── HelloServantImpl.java
└── resources
└── hello.tars
The following configuration needs to be added in pom.xml:
Spring boot and Tars framework dependency
<properties>
<spring-boot.version>2.3.5.RELEASE</spring-boot.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>com.tencent.tars</groupId>
<artifactId>tars-spring-boot-starter</artifactId>
<version>2.0.0</version>
</dependency>
</dependencies>Plugin dependency
<!--tars2java plugin-->
<plugin>
<groupId>com.tencent.tars</groupId>
<artifactId>tars-maven-plugin</artifactId>
<version>2.0.0</version>
<configuration>
<tars2JavaConfig>
<!-- tars file location -->
<tarsFiles>
<tarsFile>${basedir}/src/main/resources/hello.tars</tarsFile>
</tarsFiles>
<!-- Source file encoding -->
<tarsFileCharset>UTF-8</tarsFileCharset>
<!-- Generate server code -->
<servant>true</servant>
<!-- Generated source code encoding -->
<charset>UTF-8</charset>
<!-- Generated source code directory -->
<srcPath>${basedir}/src/main/java</srcPath>
<!-- Generated source code package prefix -->
<packagePrefixName>com.qq.tars.quickstart.server.</packagePrefixName>
</tars2JavaConfig>
</configuration>
</plugin>
<!--package plugin-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>2.6</version>
<configuration>
<archive>
<manifestEntries>
<Class-Path>conf/</Class-Path>
</manifestEntries>
</archive>
</configuration>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<!--set mainclass-->
<mainClass>com.qq.tars.quickstart.server.QuickStartApplication</mainClass>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</executions>
</plugin>Tars has its own interface file format. First, we need to define the Tars interface file. Create a new hello.tars file in the resources directory with the following content:
module TestApp
{
interface Hello
{
string hello(int no, string name);
};
};
Then we need to convert the Tars interface file to the server interface code using the tars-maven-plugin. In the project
root directory, execute mvn tars: tars2java to get HelloServant.java, the content is as follows:
@Servant
public interface HelloServant {
public String hello(int no, String name);
}Next we need to implement the generated server interface. Create a new HelloServantImpl.java file, implement the HelloServant.java interface, and expose the service through the @TarsServant annotation, where 'HelloObj' is the servant name, corresponding to the name in the web management platform.
@TarsServant("HelloObj")
public class HelloServantImpl implements HelloServant {
@Override
public String hello(int no, String name) {
return String.format("hello no=%s, name=%s, time=%s", no, name, System.currentTimeMillis());
}
}Finally, add @EnableTarsServer annotation in the spring boot startup class QuickStartApplication to enable Tars service:
@SpringBootApplication
@EnableTarsServer
public class QuickStartApplication {
public static void main(String[] args) {
SpringApplication.run(QuickStartApplication.class, args);
}
}Using spring-boot-maven-plugin, execute mvn package in the root directory to package it into a jar.
This guide gives you a quick introduction to Tars in Java through simple client example client
├── pom.xml
└── src
└── main
├── java
│ └── tars
│ └── testapp
│ ├── HelloPrx.java
│ ├── HelloPrxCallback.java
│ ├── App.java
│ └── impl
│ └── ClientServantImpl.java
└── resources
├── hello.tars
└── client.tars
The following configuration needs to be added in pom.xml:
Spring boot and Tars framework dependency
<properties>
<spring-boot.version>2.0.3.RELEASE</spring-boot.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>com.tencent.tars</groupId>
<artifactId>tars-spring-boot-starter</artifactId>
<version>2.0.0</version>
</dependency>
</dependencies>Plugin dependency
<!--tars2java plugin-->
<plugin>
<groupId>com.tencent.tars</groupId>
<artifactId>tars-maven-plugin</artifactId>
<version>2.0.0</version>
<configuration>
<tars2JavaConfig>
<!-- tars file location -->
<tarsFiles>
<tarsFile>${basedir}/src/main/resources/hello.tars</tarsFile>
</tarsFiles>
<!-- Source file encoding -->
<tarsFileCharset>UTF-8</tarsFileCharset>
<!-- Generate server code -->
<servant>false</servant>
<!-- Generated source code encoding -->
<charset>UTF-8</charset>
<!-- Generated source code directory -->
<srcPath>${basedir}/src/main/java</srcPath>
<!-- Generated source code package prefix -->
<packagePrefixName>com.tencent.tars.client.</packagePrefixName>
</tars2JavaConfig>
</configuration>
</plugin>
<!--package plugin-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>2.6</version>
<configuration>
<archive>
<manifestEntries>
<Class-Path>conf/</Class-Path>
</manifestEntries>
</archive>
</configuration>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<!--set mainclass-->
<mainClass>com.tencent.tars.App</mainClass>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</executions>
</plugin>After the server service development is completed, we first need to obtain the client interface code of the server
service. Copy the hello.tars file on the server side to the resources directory, and execute mvn tars: tars2java in
the project root directory to get HelloPrx.java. At this time, the proxy interface of the server service is obtained,
and three calling methods are provided, namely synchronous call, asynchronous call and promise call.
@Servant
public interface HelloPrx {
String hello(int no, String name);
CompletableFuture<String> promise_hello(int no, String name);
String hello(int no, String name, @TarsContext java.util.Map<String, String> ctx);
void async_hello(@TarsCallback HelloPrxCallback callback, int no, String name);
void async_hello(@TarsCallback HelloPrxCallback callback, int no, String name, @TarsContext java.util.Map<String, String> ctx);
}The promise call is a new feature of Tars v2.0.0. For specific use, please refer to the Tars file reference.
Then define the interface file of the client service. Create a new client.tars file in the resources directory with the following content:
module TestApp
{
interface Client
{
string rpcHello(int no, string name);
};
};
Next, we need to use the tars-maven-plugin to generate client service interface code. Modify the tars2java plugin
dependency of pom.xml as follows. Note that <servant> </ servant> is set to true.
<!--tars2java plugin-->
<plugin>
<groupId>com.tencent.tars</groupId>
<artifactId>tars-maven-plugin</artifactId>
<version>2.0.0</version>
<configuration>
<tars2JavaConfig>
<!-- tars file location -->
<tarsFiles>
<tarsFile>${basedir}/src/main/resources/client.tars</tarsFile>
</tarsFiles>
<!-- Source file encoding -->
<tarsFileCharset>UTF-8</tarsFileCharset>
<!-- Generate server code -->
<servant>true</servant>
<!-- Generated source code encoding -->
<charset>UTF-8</charset>
<!-- Generated source code directory -->
<srcPath>${basedir}/src/main/java</srcPath>
<!-- Generated source code package prefix -->
<packagePrefixName>com.tencent.tars.client.</packagePrefixName>
</tars2JavaConfig>
</configuration>
</plugin>In the root directory of the project, execute mvn tars: tars2java again to get ClientServant.java. The contents are as
follows:
@Servant
public interface ClientServant {
public String rpcHello(int no, String name);
}We need to implement the generated client service interface. Create a new ClientServantImpl.java file, implement the HelloServant.java interface, and expose the service through the @TarsServant annotation, where 'HelloObj' is the servant name, corresponding to the name in the web management platform.
By adding the @TarsClient annotation to the client properties, the corresponding service can be automatically injected. If only the Obj name is filled, the default value is used to inject the client. In addition, the client configuration can be customized in the annotation, such as setting the synchronous call timeout time.
@TarsServant("ClientObj")
public class ClientServantImpl implements ClientServant {
@TarsClient("TestServer.HelloServer.HelloObj")
HelloPrx helloPrx;
String res = "";
@Override
public String rpcHello(int no, String name) {
//sync call
String syncres = helloPrx.hello(1000, "Hello World");
res += "sync_res: " + syncres + " ";
//async call
helloPrx.async_hello(new HelloPrxCallback() {
@Override
public void callback_expired() {
}
@Override
public void callback_exception(Throwable ex) {
}
@Override
public void callback_hello(String ret) {
res += "async_res: " + ret + " ";
}
}, 1000, "HelloWorld");
//promise call
helloPrx.promise_hello(1000, "hello world").thenCompose(x -> {
res += "promise_res: " + x;
return CompletableFuture.completedFuture(0);
});
return res;
}
}Finally, add @EnableTarsServer annotation in the spring boot startup class App to enable Tars service:
@SpringBootApplication
@EnableTarsServer
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
}Using spring-boot-maven-plugin, execute mvn package in the root directory to package it into a jar.
Tars-java is compatible with the Spring Cloud system, users can integrate the Tars-java into Spring Cloud.
| Directory | Features |
|---|---|
| net | Source code implementation of Java language net framework |
| core | Source code implementation of Java language rpc framework |
| tools | Source code implementation of framework tools, maven plug-ins, etc |
| examples | Sample code for the Java language framework |
| distributedContext | Source code implementation of Java language framework's distributed context |
| protobuf | Source code implementation of pb protocol support |
| spring | Source code implementation of spring framework support |