docs/wiki/en_quickstart.md
The quick start gives very basic example of running server and client on the same machine. For more details about using and developing Motan, please jump to Documents.
The minimum requirements to run the quick start are:
Add dependencies to pom.
<dependency>
<groupId>com.weibo</groupId>
<artifactId>motan-core</artifactId>
<version>RELEASE</version>
</dependency>
<dependency>
<groupId>com.weibo</groupId>
<artifactId>motan-transport-netty</artifactId>
<version>RELEASE</version>
</dependency>
<!-- dependencies blow were only needed for spring-based features -->
<dependency>
<groupId>com.weibo</groupId>
<artifactId>motan-springsupport</artifactId>
<version>RELEASE</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>RELEASE</version>
</dependency>
Create an interface for both service provider and consumer.
src/main/java/quickstart/FooService.java
package quickstart;
public interface FooService {
public String hello(String name);
}
Write an implementation, create and start RPC Server.
src/main/java/quickstart/FooServiceImpl.java
package quickstart;
public class FooServiceImpl implements FooService {
public String hello(String name) {
System.out.println(name + " invoked rpc service");
return "hello " + name;
}
}
src/main/resources/motan_server.xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:motan="http://api.weibo.com/schema/motan"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://api.weibo.com/schema/motan http://api.weibo.com/schema/motan.xsd">
<!-- service implemention bean -->
<bean id="serviceImpl" class="quickstart.FooServiceImpl" />
<!-- exporting service by Motan -->
<motan:service interface="quickstart.FooService" ref="serviceImpl" export="8002" />
</beans>
src/main/java/quickstart/Server.java
package quickstart;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
public class Server {
public static void main(String[] args) throws InterruptedException {
ApplicationContext applicationContext = new ClassPathXmlApplicationContext("classpath:motan_server.xml");
System.out.println("server start...");
}
}
Execute main function in Server will start a Motan server listening on port 8002.
Create and start RPC Client.
src/main/resources/motan_client.xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:motan="http://api.weibo.com/schema/motan"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://api.weibo.com/schema/motan http://api.weibo.com/schema/motan.xsd">
<!-- reference to the remote service -->
<motan:referer id="remoteService" interface="quickstart.FooService" directUrl="localhost:8002"/>
</beans>
src/main/java/quickstart/Client.java
package quickstart;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
public class Client {
public static void main(String[] args) throws InterruptedException {
ApplicationContext ctx = new ClassPathXmlApplicationContext("classpath:motan_client.xml");
FooService service = (FooService) ctx.getBean("remoteService");
System.out.println(service.hello("motan"));
}
}
Execute main function in Client will invoke the remote service and print response.
In cluster environment, the external service discovery components such as Consul or ZooKeeper is needed to support the use of Motan.
# Taking Linux as an example
wget https://releases.hashicorp.com/consul/0.6.4/consul_0.6.4_linux_amd64.zip
unzip consul_0.6.4_linux_amd64.zip
sudo mv consul /bin
Starting the test environment：
consul agent -dev
UI backend http://localhost:8500/ui
Add motan-registry-consul in the pom of server and client.
<dependency>
<groupId>com.weibo</groupId>
<artifactId>motan-registry-consul</artifactId>
<version>RELEASE</version>
</dependency>
Add the definition of consul registry in the configuration of server and client.
<motan:registry regProtocol="consul" name="my_consul" address="127.0.0.1:8500"/>
Change the way of service discovery to service discovery through registry in the configuration of server and client.
server:
<motan:service interface="quickstart.FooService" ref="serviceImpl" registry="my_consul" export="8002" />
client:
<motan:referer id="remoteService" interface="quickstart.FooService" registry="my_consul"/>
After the server starts, you SHOULD call heartbeat switcher explicitly in order to start heartbeat for Consul.
MotanSwitcherUtil.setSwitcherValue(MotanConstants.REGISTRY_HEARTBEAT_SWITCHER, true)
Go to UI backend. Verify whether the service is normal.
Start client, call service.
Install and start ZooKeeper:
wget http://mirrors.cnnic.cn/apache/zookeeper/zookeeper-3.4.8/zookeeper-3.4.8.tar.gz
tar zxvf zookeeper-3.4.8.tar.gz
cd zookeeper-3.4.8/conf/
cp zoo_sample.cfg zoo.cfg
cd ../
sh bin/zkServer.sh start
Add motan-registry-zookeeper in the pom of server and client.
<dependency>
<groupId>com.weibo</groupId>
<artifactId>motan-registry-zookeeper</artifactId>
<version>RELEASE</version>
</dependency>
Add the definition of ZooKeeper registry in the configuration of server and client.
single node ZooKeeper:
<motan:registry regProtocol="zk" name="my_zookeeper" address="127.0.0.1:2181"/>
multi-nodes ZooKeeper:
<motan:registry regProtocol="zk" name="my_zookeeper" address="127.0.0.1:2181,127.0.0.1:2182,127.0.0.1:2183"/>
Change the way of service discovery to registry in the configuration of server and client.
server:
<motan:service interface="quickstart.FooService" ref="serviceImpl" registry="my_zookeeper" export="8002" />
client:
<motan:referer id="remoteService" interface="quickstart.FooService" registry="my_zookeeper"/>
After the server starts, you SHOULD call heartbeat switcher explicitly in order to start heartbeat for Zookeeper.
MotanSwitcherUtil.setSwitcherValue(MotanConstants.REGISTRY_HEARTBEAT_SWITCHER, true)
Start client, call service.
YAR protocol is a rpc extension of php,motan framework can provide yar protocol for RPC services 1、add motan-protocol-yar.jar
<dependency>
<groupId>com.weibo</groupId>
<artifactId>motan-protocol-yar</artifactId>
<version>RELEASE</version>
</dependency>
2、Add annotations @YarConfig to the service interface class to declare the uri of the service
@YarConfig(path = "/openapi/yarserver/test")
public interface YarService {
public String hello(String name);
｝
3、Configure protocol name = "yar"
<motan:protocol id="demoYar" name="yar" .../>
4、Configure the export of service, using yar protocol to provide services
<motan:service interface="com.weibo.motan.demo.service.YarService"
export="demoYar:8003" .../>
Check motan-demo module to get specific configuration. YAR protocol use yar-java to parse，and can be use directly when using java as client
1、Declare Annotation to specify the name of the package to be resolved
@Bean
public AnnotationBean motanAnnotationBean() {
AnnotationBean motanAnnotationBean = new AnnotationBean();
motanAnnotationBean.setPackage("com.weibo.motan.demo.server");
return motanAnnotationBean;
}
2、Configure the bean object of ProtocolConfig, RegistryConfig,and BasicServiceConfig, which is consistent with the protocol, registry, and basicService tags in the xml configuration
@Bean(name = "demoMotan")
public ProtocolConfigBean protocolConfig1() {
ProtocolConfigBean config = new ProtocolConfigBean();
config.setDefault(true);
config.setName("motan");
config.setMaxContentLength(1048576);
return config;
}
@Bean(name = "registryConfig1")
public RegistryConfigBean registryConfig() {
RegistryConfigBean config = new RegistryConfigBean();
config.setRegProtocol("local");
return config;
}
@Bean
public BasicServiceConfigBean baseServiceConfig() {
BasicServiceConfigBean config = new BasicServiceConfigBean();
config.setExport("demoMotan:8002");
config.setGroup("testgroup");
config.setAccessLog(false);
config.setShareChannel(true);
config.setModule("motan-demo-rpc");
config.setApplication("myMotanDemo");
config.setRegistry("registryConfig1");
return config;
}
3、Add the @MotanService annotation to the implementation class of the service. The configuration parameters of the annotation are the same as the service tag of the xml configuration.
@MotanService(export = "demoMotan:8002")
public class MotanDemoServiceImpl implements MotanDemoService {
public String hello(String name) {
System.out.println(name);
return "Hello " + name + "!";
}
}
4、Using spring-boot to boot service
@EnableAutoConfiguration
@SpringBootApplication
public class SpringBootRpcServerDemo {
public static void main(String[] args) {
System.setProperty("server.port", "8081");
ConfigurableApplicationContext context = SpringApplication.run(SpringBootRpcServerDemo.class, args);
MotanSwitcherUtil.setSwitcherValue(MotanConstants.REGISTRY_HEARTBEAT_SWITCHER, true);
System.out.println("server start...");
}
}
Check motan-demo module to get specific configuration
1、Declare the configuration bean for Annotation, protocolConfig, and RegistryConfig. The server is configured similarly to the server.
2、Configuring basicRefererConfig bean
@Bean(name = "motantestClientBasicConfig")
public BasicRefererConfigBean baseRefererConfig() {
BasicRefererConfigBean config = new BasicRefererConfigBean();
config.setProtocol("demoMotan");
config.setGroup("motan-demo-rpc");
config.setModule("motan-demo-rpc");
config.setApplication("myMotanDemo");
config.setRegistry("registry");
config.setCheck(false);
config.setAccessLog(true);
config.setRetries(2);
config.setThrowException(true);
return config;
}
3、Add the @MotanReferer annotation to the object that uses the motan service. The registration configuration is consistent with the referer tag in xml mode
@RestController
public class HelloController {
@MotanReferer(basicReferer = "motantestClientBasicConfig", group = "testgroup", directUrl = "127.0.0.1:8002")
MotanDemoService service;
@RequestMapping("/")
@ResponseBody
public String home() {
String result = service.hello("test");
return result;
}
}
4、Using spring-boot to boot client
@EnableAutoConfiguration
@SpringBootApplication
public class SpringBootRpcClientDemo {
public static void main(String[] args) {
SpringApplication.run(SpringBootRpcClientDemo.class, args);
}
}
Check motan-demo module to get specific configuration
Motan support OpenTracingthrough the filter's SPI extension mechanism, which can support any trace implementation that implements the OpenTracing standard. The following steps are required to use OpenTracing.
1、add filter-opentracing to pom
<dependency>
<groupId>com.weibo</groupId>
<artifactId>filter-opentracing</artifactId>
<version>RELEASE</version>
</dependency>
2、If the third-party trace tool declares the io.opentracing.Tracer's SPI extension, you can directly introduce a third-party trace to the jar package. If the third party does not make a statement, turn to the third step.
3、Customize a TracerFactory implementation TracerFactory interface, through getTracer () to get different tracer implementation. Set the tracerFactory of the OpenTracingContext to a custom TracerFactory.
You can refer to the filter-opentracing module src / test / java / com.weibo.api.motan.filter.opentracing.zipkin.demo package under the server and client side to achieve.