# 目录 #
> * [环境搭建] (#main-chapter-1)
> * [服务开发] (#main-chapter-2)
> * [管理系统] (#main-chapter-3)
> * [服务命名] (#main-chapter-4)
> * [服务部署] (#main-chapter-5)

# 框架快速入门

## 环境搭建 <a id="main-chapter-1"></a>

### 环境依赖 

- JDK1.6或以上版本
- Maven 2.2.1或以上版本

### 构建工程 

通过IDE或者maven创建一个maven web项目，
这里以eclipse为例，File -> New -> Project -> Maven Project -> maven-archetype-webapp，再输入groupId、artifactId，生成完成之后可以通过eclipse进行导入，目录结构如下
    
	hello_server_project
	|___src
	|	|___main
	|		|___java
	|		|___resource
	|		|___scripts
	|		|___webapp
	|___test
	|___target
	|___pom.xml


### 依赖配置
在构建项目中pom.xml中添加依赖jar包

- 框架依赖配置

    	<dependency>
			<groupId>qq-cloud-central</groupId>
			<artifactId>tars-server</artifactId>
			<version>1.0.1</version>
			<type>jar</type>
		</dependency>

- 插件依赖配置

		<plugin>
			<groupId>qq-cloud-central</groupId>
			<artifactId>tars-maven-plugin</artifactId>
			<version>1.0.1</version>
			<configuration>
				<tars2JavaConfig>
					<tarsFiles>
						<tarsFile>${basedir}/src/main/resources/hello.tars</tarsFile>
					</tarsFiles>
					<tarsFileCharset>UTF-8</tarsFileCharset>
					<servant>true</servant>
					<srcPath>${basedir}/src/main/java</srcPath>
					<charset>UTF-8</charset>
					<packagePrefixName>com.qq.tars.quickstart.server.</packagePrefixName>
				</tars2JavaConfig>
			</configuration>
		</plugin>

## 服务开发 <a id="main-chapter-2"></a>

### 接口文件定义

接口文件定义是通过Tars接口描述语言来定义，在src/main/resources目录下建立hello.tars文件，内容如下
    	
	module TestApp 
	{
		interface Hello
		{
		    string hello(int no, string name);
		};
	};

### 接口文件编译

提供插件编译生成java代码，在tars-maven-plugin添加生成java文件配置

	<plugin>
		<groupId>qq-cloud-central</groupId>
		<artifactId>tars-maven-plugin</artifactId>
		<version>1.0.1</version>
		<configuration>
			<tars2JavaConfig>
				<!-- tars文件位置 -->
				<tarsFiles>
					<tarsFile>${basedir}/src/main/resources/hello.tars</tarsFile>
				</tarsFiles>
				<!-- 源文件编码 -->
				<tarsFileCharset>UTF-8</tarsFileCharset>
				<!-- 生成服务端代码 -->
				<servant>true</servant>
				<!-- 生成源代码编码 -->
				<charset>UTF-8</charset>
				<!-- 生成的源代码目录 -->
				<srcPath>${basedir}/src/main/java</srcPath>
				<!-- 生成源代码包前缀 -->
				<packagePrefixName>com.qq.tars.quickstart.server.</packagePrefixName>
			</tars2JavaConfig>
		</configuration>
	</plugin>

在工程根目录下执行mvn tars:tars2java
			
	@Servant
	public interface HelloServant {

		public String hello(int no, String name);
	}	

### 服务接口实现

新创建一个HelloServantImpl.java文件，实现HelloServant.java接口

	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());
	}


### 服务暴露配置

在WEB-INF下创建一个servants.xml的配置文件，服务编写后需要进程启动时加载配置暴露服务，配置如下
			
	<?xml version="1.0" encoding="UTF-8"?>
	<servants>
		<servant name="HelloObj">
			<home-api>com.qq.tars.quickstart.server.testapp.HelloServant</home-api>
			<home-class>com.qq.tars.quickstart.server.testapp.impl.HelloServantImpl</home-class>
		</servant>
	</servants>

### 服务编译打包

在工程根目录下执行 mvn package生成war包，后续可以管理系统进行发布。

### 客户端同步/异步调用服务

- 构建客户端工程项目
- 添加依赖
    	
		<dependency>
			<groupId>qq-cloud-central</groupId>
			<artifactId>tars-client</artifactId>
			<version>1.0.1</version>
			<type>jar</type>
		</dependency>    

- 添加插件
		
		<plugin>
			<groupId>qq-cloud-central</groupId>
			<artifactId>tars-maven-plugin</artifactId>
			<version>1.0.1</version>
			<configuration>
				<tars2JavaConfig>
					<!-- tars文件位置 -->
					<tarsFiles>
						<tarsFile>${basedir}/src/main/resources/hello.tars</tarsFile>
					</tarsFiles>
					<!-- 源文件编码 -->
					<tarsFileCharset>UTF-8</tarsFileCharset>
					<!-- 生成代码，PS：客户端调用，这里需要设置为false -->
					<servant>false</servant>
					<!-- 生成源代码编码 -->
					<charset>UTF-8</charset>
					<!-- 生成的源代码目录 -->
					<srcPath>${basedir}/src/main/java</srcPath>
					<!-- 生成源代码包前缀 -->
					<packagePrefixName>com.qq.tars.quickstart.client.</packagePrefixName>
				</tars2JavaConfig>
			</configuration>
		</plugin>

- 根据服务tars接口文件生成代码

	    @Servant
		public interface HelloPrx {
	
			public String hello(int no, String name);
		
			public String hello(int no, String name, @TarsContext java.util.Map<String, String> ctx);
		
			public void async_hello(@TarsCallback HelloPrxCallback callback, int no, String name);
		
			public void async_hello(@TarsCallback HelloPrxCallback callback, int no, String name, @TarsContext java.util.Map<String, String> ctx);
		}

- 同步调用

        public static void main(String[] args) {
			CommunicatorConfig cfg = new CommunicatorConfig();
			//构建通信器
	        Communicator communicator = CommunicatorFactory.getInstance().getCommunicator(cfg);
			//通过通信器，生成代理对象
	        HelloPrx proxy = communicator.stringToProxy(HelloPrx.class, "TestApp.HelloServer.HelloObj");
	        String ret = proxy.hello(1000, "HelloWorld");
	        System.out.println(ret);
    	}

- 异步调用

        public static void main(String[] args) {
			CommunicatorConfig cfg = new CommunicatorConfig();
			//构建通信器
	        Communicator communicator = CommunicatorFactory.getInstance().getCommunicator(cfg);
			//通过通信器，生成代理对象
	        HelloPrx proxy = communicator.stringToProxy(HelloPrx.class, "TestApp.HelloServer.HelloObj");
			proxy.async_hello(new HelloPrxCallback() {
				
				@Override
				public void callback_expired() {
				}
				
				@Override
				public void callback_exception(Throwable ex) {
				}
				
				@Override
				public void callback_hello(String ret) {
					System.out.println(ret);
				}
			}, 1000, "HelloWorld");
    	}


## 管理系统 <a id="main-chapter-3"></a>

进入管理系统，如下图

![tars](images/tars_web_index.png)

管理系统的菜单树下，有以下功能：

- 业务管理：包括已部署的服务，以及服务管理、发布管理、服务配置、服务监控、特性监控等；

- 运维管理：包括服务部署、扩容、模版管理等；


## 服务命名 <a id="main-chapter-4"></a>

使用Tars框架的服务，其的服务名称有三个部分：

- APP：应用名，标识一组服务的一个小集合，在Tars系统中，应用名必须唯一。例如：TestApp；

- Server：服务名，提供服务的进程名称，Server名字根据业务服务功能命名，一般命名为：XXServer，例如HelloServer；

- Servant：服务者，提供具体服务的接口或实例。例如:HelloImp；

说明：

一个Server可以包含多个Servant，系统会使用服务的App + Server + Servant，进行组合，来定义服务在系统中的路由名称，称为路由Obj，其名称在整个系统中必须是唯一的，以便在对外服务时，能唯一标识自身。

因此在定义APP时，需要注意APP的唯一性。

例如：TestApp.HelloServer.HelloObj。


## 服务部署 <a id="main-chapter-5"></a>

### 部署申请 ###

点击主菜单“运维管理”－〉“服务部署”

如下图：

![tars](images/tars_java_quickstart_bushu1.png)

-	“应用”指你的服务程序归在哪一个应用下，例如：“TestApp”。
-	“服务名称”指你的服务程序的标识名字，例如：“HelloServer”。
-	“服务类型”指你的服务程序用什么语言写的，例如：java的选择“tars_java”。
-	“模版“ 指你的服务程序在启动时，设置的配置文件的名称，默认用”tars.tarsjavadefault“即可。
-	“节点“ 指服务部署的机器IP。
-	“Set分组“ 指设置服务的Set分组信息，Set信息包括3部分：Set名、Set地区、Set组名。
-	“OBJ名称“ 指Servant的名称。
-	“OBJ绑定IP“ 指服务绑定的机器IP，一般与节点一样。
-	“端口“ 指OBJ要绑定的端口。
-	“端口类型“ 指使用TCP还是UDP。
-	“协议“ 指应用层使用的通信协议，Tars框架默认使用tars协议。
-	“线程数“ 指业务处理线程的数目。
-	“最大连接数“ 指支持的最大连接数。
-	“队列最大长度“ 指请求接收队列的大小。
-	“队列超时时间“ 指请求接收队列的超时时间。

点击“提交“，成功后，菜单数下的TestApp应用将出现HelloServer名称，同时将在右侧看到你新增的服务程序信息，如下图：

![tars](images/tars_java_quickstart_bushu2.png)

在管理系统上的部署暂时先到这里，到此为止，只是使你的服务在管理系统上占了个位置，真实程序尚未发布。

### 服务发布

在管理系统的菜单树下，找到你部署的服务，点击进入服务页面。 

选择“发布管理”，选中要发布的节点，点击“发布选中节点”，点击“上传发布包”，选择已经编译好的发布包，如下图：

![tars](images/tars_java_quickstart_upload.png)

 上传好发布包后，点击“选择发布版本”下拉框就会出现你上传的服务程序，选择最上面的一个（最新上传的）。如下图：

 ![tars](images/tars_java_quickstart_patch.png)

 点击“发布”，服务开始发布，发布成功后，出现下面的界面，如下图：

 ![tars](images/tars_java_quickstart_patchresult.png)
 
若失败的话，可能是命名问题，上传问题，以及其他环境问题。

