本文依照 知识共享许可协议(署名-非商业性使用-禁止演绎) 发布。
感谢@严禁扯淡 的修改建议。

2017-2-9:更新异步协同部分。

先放两个链接：
源文档
Github repository.

话说用Java这么多年，没给社区做过什么贡献。这次趁使用Vert.x3的机会，简单翻译了核心包的手册。

Vert.x3的手册简洁明了，过一遍即可轻松入门。所以诸君若是看到什么无法理解的，必定是我的译文有问题（嘿嘿，水平低，见谅）。

部分名词对照表：

• handler：事件处理器
• event loop：事件循环(线程)
• verticle：Vert.x的专有名词。指代Vert.x中基本的功能单元，一个Vert.x应用应该是由一组verticles构成的。
• worker：顾名思义，干活的(线程)。对应文档中有worker thread pool，worker verticle(Vert.x里的work verticle与标准版verticle区别较大)。
• event bus：事件总线

Vert.x核心包提供如下的功能：

• TCP客户端与服务器
• HTTP客户端与服务器（包含Websocket支持）
• 事件总线（Event bus）
• 共享数据-局部的map和集群下的分布式map
• 定时或延迟的处理
• 部署、卸载verticle
• 数据报文套接字（datagram socket）
• DNS客户端
• 文件系统存取
• 高可用性
• 集群

核心包提供的功能是相当底层的。这意味着没有诸如数据库存取、认证、高级web功能此类的组件，你可以在Vert.x ext（扩展包）找到以上这些。

Vert.x 的核心小且轻量，诸位可以各取所需。它可以整个的嵌入你现有的应用当中，不需要为了使用Vert.x而以特别的方式组织你的应用。

你可以在任何Vert.x支持的语言中使用核心包。但是有一点要提一下，我们不会迫使你在Javascript或者Ruby里使用为Java准备的API；毕竟不同的语言有不同的约定和惯用法，强迫Ruby开发者使用Java的惯用法确实比较古怪。相反的，我们为每一种语言都生成了等价于核心Java API的惯用法(idiomatic)。

现在开始，我们将使用核心包（core）指代Vert.x core。

如果你使用Maven或Gradle，把下列几行加入项目描述符的依赖配置即可使用核心包的API：

• Maven (in your pom.xml):

<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-core</artifactId>
    <version>3.2.1</version>
</dependency>

• Gradle (in your build.gradle file):
  compile io.vertx:vertx-core:3.2.1

下面让我们看看核心包里的各种特性。

开始使用Vert.x

注意：这里所述大部分都是Java适用的，语言相关的部分需要以某种方式进行转换。

在Vert.x里，如果没有Vertx对象，那几乎什么都做不了！
Vertex对象是Vert.x的控制中心，许多功能都通过它实现。包括创建客户端和服务器、获取事件总线（event bus）的引用、设置定时器，等等。

那么，如何获取它的实例呢？

如果你在程序中嵌入Vert.x，那么可以像下面这样创建实例：
Vertx vertx = Vertx.vertx();

当你使用Verticle时

注意：绝大部分应用其实只需要一个Vert.x实例；当然，你也可以创建多个实例。例如，两个总线需要隔离时或客户端服务器需分组时。

创建Vert.x实例时指定可选项（option）

创建Vert.x实例时，如果缺省选项不合适，你也可以设定一些值：
Vertx vertx = Vertx.vertx(new VertxOptions().setWorkerPoolSize(40));

VertxOptions对象有很多设置项，你可以配置集群（clustering）、高可用性（high availability），worker 线程池的大小（pool sizes）等等。详细的内容请参见Javadoc。

创建集群模式（clustered）的Vert.x对象

如果你在使用Vert.x的集群模式（更多细节请参考下面的event bus一节，关于集群下的event bus），记得创建Vert.x对象也是异步的。

为了把集群里不同的vertx实例组织在一起，通常需要花一点时间（可能是几秒钟）。在这段时间里，为了不阻塞调用线程（the calling thread），结果会以异步的方式返回。

Are you fluent？（fluent狂人，别走）

你可能已经注意到，在前面的例子中，我们使用了流式(fluent)的API。

流式API是指多个方法可以用链式的方式一起调用。例如：
request.response().putHeader("Content-Type", "text/plain").write("some text").end();

这在Vert.x的API里是很普遍的模式，你要试着习惯它。 :)

链式调用允许你更简洁的编写代码。当然，如果你不喜欢这种方式，这也不是必须的。你可以愉快地忽略这些，然后像下面这样写：

HttpServerResponse response = request.response();
response.putHeader("Content-Type", "text/plain");
response.write("some text");
response.end();

不要调用我们，我们会调用你（Don’t call us, we’ll call you.）

大部分Vert.x API 都是事件驱动的。这意味着如果你对Vert.x里发生的某事感兴趣，Vert.x会以向你发送事件（events）的方式通知你。

例如下面的事件：

• 定时器被触发
• socket收到了一些数据
• 一些数据已经从磁盘上被读取
• 某个异常产生了
• HTTP服务器接受了一个请求

通过提供handlers，你可以处理这些事件。例如定义一个定时器事件：

vertx.setPeriodic(1000, id -> {
  // This handler will get called every second
  System.out.println("timer fired!");
});

或者接受一个HTTP请求：

server.requestHandler(request -> {
  // This handler will be called every time an HTTP request is received at the server
  request.response().end("hello world!");
});

如果触发了某个事件，Vert.x将会异步地(asynchronously)调用它（the handler）。

这里我们发现了Vert.x的如下重要概念。

不要阻塞我！（Don't block me!）

除了极少的例外（即某些以‘Sync’结尾的文件系统操作），Vert.x里没有API会阻塞调用线程。

如果结果可以即刻获得，它会立刻被返回。否则，通常你需要提供一个处理器，以便稍后接收事件。

没有API会阻塞线程意味着：用少量的线程，就可以处理大量的并发。

传统的阻塞API可能会在哪些地方发生呢：

• 从socket读取数据
• 写数据到磁盘
• 发消息给某个接收者，然后等待回应
• 。。很多其他状况

在上面这些案例中，你的线程在等待一个结果时不能做其他任何事，这样是很低效的。

这也意味着，如果你想使用阻塞API处理大量并发，你将需要大量的线程来防止你的应用卡住。

线程在内存（例如：栈）和上下文切换方面的开销不容忽视。

以很多现代的应用所需求的并发级别，阻塞的方式根本实现不了。

Reactor and Multi-Reactor(反应器和多路反应器？)

前面我们提到了Vert.x的API是事件驱动的，当handlers可用的时候，Vert.x会向它们传递事件。

绝大多数情况下，Vert.x通过一个叫event loop的线程调用你的handlers。

event loop可以在事件到达时持续不断地将其分发给不同的handler，因为Vert.x和你的应用中不会有什么是阻塞的。

同样，因为没什么是阻塞的，所以event loop具有在短时间内分发巨量事件的潜力。例如，单个event loop可以极迅速地处理数千的HTTP请求。

我们称之为Reactor模式。

你之前可能已经听说过它--nodejs就实现了这种模式。

标准的Reactor实现里，有一个单独的event loop(single event loop)线程，它会在所有事件到达时持续不断地将其分发给所有的handler。

单一线程的困扰在于，在任意时刻，它只能在一个cpu核心上运行。所以如果你希望你的单线程Reactor应用（或者Nodejs应用）能够运用上多核服务器的扩展能力（ scale over your multi-core server ），你需要启动多个进程并管理好它们。

Vert.x的工作方式不同于此，每个vertx实例会维护数个event loop(several event loops)。缺省情况下，我们基于机器上可用的核心数来确定这个数字，当然这个也可以设置。

不像Nodejs，这意味着单个Vert.x进程可以利用到服务器的扩展。

为了与单线程的reactor模式区分开，我们称之为Multi-Reactor模式。

注意：虽然一个Vert.x实例会维护多个event loop，但任何特定的handler都绝不会被并发地执行，在绝大多数情况下(worker verticle除外),它都会被某个固定的event loop（exact same event loop）调用。

黄金准则：不要阻塞Event Loop（Don’t Block the Event Loop）

我们已经了解了，Vert.x的API是非阻塞的，不会阻塞event loop；但是，如果你在handler中自己(yourself)阻塞了event loop，那么上面的其实都没啥用。。

如果你这么干了，那么event loop被阻塞的时候它啥都干不了。再如果你阻塞了Vert.x实例里所有的event loop，那你的应用将会陷入完全停滞的状态！

所以千万别这么干！我们已经警告过你了哈(You have been warned)。

阻塞的例子包括：

• Thread.sleep()
• 等待一个锁
• 等待一个同步锁或监视器（例如同步块（synchronized section））
• 做一个耗时的数据库操作并等待结果
• 做一个复杂的计算，耗费大量的时间
• 在循环中（Spinning in a loop）

如果上面任何一步挂住了event loop，让它花了大量时间( significant amount of time),那么你只能安心等待程序执行。

那么，什么样是大量时间( significant amount of time)呢？

这个时间，实际上取决于你的应用对并发量的需求。

如果你有单一的event loop并且想每秒处理一万个http请求，那么很明显，处理每个请求的时间不能超过0.1毫秒，所以阻塞不能超过这个时间。

这里面的计算不难，作为练习，我们将之留给读者(The maths is not hard and shall be left as an exercise for the reader)。

如果你的应用没有响应了，这可能是event loop被阻塞的信号。为了帮助诊断这样的问题，Vert.x会在检测到某个event loop一段时间后还未返回时自动打印警告日志。如果在你的日志中看见这样的警告，那你可得调查调查了。
Thread vertx-eventloop-thread-3 has been blocked for 20458 ms

为了精确定位阻塞发生在何处，Vert.x也会提供堆栈跟踪消息。

如果你想关闭这些警告或改变设置，可以在创建Vertx对象前，去VertxOptions对象里设置。

执行阻塞式代码

完美的世界里，不会有战争，也不会有饥饿。所有的API都会以异步的方式写成，小兔和小羊羔会手牵手地穿过阳光明媚的绿草地。

但是，现实世界不是这样的。。（你有关注最近的新闻吗？）
（迷之声：这篇文档生成时发生了啥？？）

事实上，不算其他大多数库，单单在JVM的子系统里就有同步的API和很多可能造成阻塞的方法。一个好的例子是JDBC，它天然就是同步的；无论怎么使劲，Vert.x也不会魔法，没办法撒一点魔力粉就让它变成异步的。

我们不会整夜不睡的去重写所有(现存的组件)使它们成为异步的，所以我们需要提供一种方式，以使在Vert.x应用里可以安全的使用“传统的”阻塞API。

就像前面讨论的，为了不妨碍event loop干其他有益的活，不能从它这直接调用阻塞操作。所以你该怎么办呢？

指定待执行的阻塞代码和一个结果处理器（result handler），然后调用executeBlocking，当阻塞代码执行完毕的时候，handler将会以异步的方式被回调（to be called back asynchronous ）。

vertx.executeBlocking(future -> {
  // Call some blocking API that takes a significant amount of time to return
  String result = someAPI.blockingMethod("hello");
  future.complete(result);
}, res -> {
  System.out.println("The result is: " + res.result());
});

缺省情况下，如果executeBlocking 在同一上下文环境中（例如同一个verticle）被多次调用，那么不同的executeBlocking 会被顺序地执行（即一个接一个）。

如果你不在意executeBlocking 执行的顺序，那么你可以将ordered参数设置为false。这种情况下，worker pool有可能会并行地执行executeBlocking。

另一种执行阻塞代码的方法是在worker verticle中干这事。

worker verticle总是由worker pool里的线程来执行。

异步协同

多个异步结果的协同可以由Vert.x的futures来实现。

CompositeFuture.all接受数个future参数（到6为止）并返回一个future；当所有的future都成功了，就返回成功(succeeded)的future，否则返回失败(failed)的future：

Future<HttpServer> httpServerFuture = Future.future();
httpServer.listen(httpServerFuture.completer());

Future<NetServer> netServerFuture = Future.future();
netServer.listen(netServerFuture.completer());

CompositeFuture.all(httpServerFuture, netServerFuture).setHandler(ar -> {
  if (ar.succeeded()) {
    // All server started
  } else {
    // At least one server failed
  }
});

由completer返回的handler会完成这个future。

CompositeFuture.any接受数个future参数（到6为止）并返回一个future；只要有一个future成功了，那返回的future也成功(succeeded)，否则就失败(failed)：

Future<String> future1 = Future.future();
Future<String> future2 = Future.future();
CompositeFuture.any(future1, future2).setHandler(ar -> {
  if (ar.succeeded()) {
    // At least one is succeeded
  } else {
    // All failed
  }
});

2017-2-9 更新

新版CompositeFuture 的API 中增加了与all类似的系列方法：join 。
看文档的说明，all 和 join 的区别在于：

如果参数列表中的某个Future 失败了，那么all 不会继续等，这个CompositeFuture将被标记为失败并完成；而join会继续等待直到所有参数完成（不管成功与否）。

compose可以用来链式调用future：

FileSystem fs = vertx.fileSystem();

Future<Void> fut1 = Future.future();
Future<Void> fut2 = Future.future();

fs.createFile("/foo", fut1.completer());
fut1.compose(v -> {
  fs.writeFile("/foo", Buffer.buffer(), fut2.completer());
}, fut2);
fut2.compose(v -> {
  fs.move("/foo", "/bar", startFuture.completer());
}, startFuture);

Verticles

Vert.x有一个简单的、可扩展的，类似actor的部署方式（actor-like deployment ）和开箱即用的并发模型，这方面可以节省下你亲自动手的时间精力。

这个模型是完全可选的，如果你不想，Vert.x并不会强迫你以这种方式创建自己的应用。。

这个模型并未严格地实现actor模型，但确实与其有相似之处，尤其在并发性、扩展，部署方面。

为了使用这个模型，你需要将代码写成verticles的集合。

verticles是由Vert.x部署和运行的代码块。verticles可以由任何Vert.x支持的语言写成，并且单独的应用可以包含多种语言写就的verticles。

你可以把verticle看成有点像Actor Model里的actor。

一个典型的应用由同一时间运行在同一Vert.x实例里的很多verticle实例组成的。不同的verticle实例之间通过在event bus上向彼此发送消息来通信。

编写verticle

verticle类必须实现Verticle接口。

你可以直接实现这个接口，但通常有个更简单的办法，就是继承下面这个抽象类：AbstractVerticle。

举个例子：

public class MyVerticle extends AbstractVerticle {

  // Called when verticle is deployed
  public void start() {
  }

  // Optional - called when verticle is undeployed
  public void stop() {
  }

}

通常你需要像上面的例子一样，重载start方法。

Vert.x部署verticle时，会调用其start方法。当该start方法完成时，就认为该verticle已启动。

你也可以选择重载stop方法，当verticle被卸载（undeployed）时会调用这个方法。同样，stop方法完成时，会认为verticle已被终止。

异步verticle的启动和终止

有时候你可能想在verticle启动时做点耗时的事，除非完成了，否则不应该认定verticle已成功部署。比如你可能想在start方法里部署其他的verticles。

你不能在start方法里阻塞地等待其他verticles部署完成，这会打破我们的黄金准则。

那该怎么做呢？

合适的途径是实现异步的start方法。这个版本的start方法有一个future参数，这个方法返回时verticle并不会被认定已经部署完成。

等干完所有活之后（例如启动其他的verticles）你就可以调用future对象的complete（或者fail）方法；这是一个信号，标记你这里已经都完成了。

下面有个例子：

public class MyVerticle extends AbstractVerticle {

  public void start(Future<Void> startFuture) {
    // Now deploy some other verticle:

    vertx.deployVerticle("com.foo.OtherVerticle", res -> {
      if (res.succeeded()) {
        startFuture.complete();
      } else {
        startFuture.fail();
      }
    });
  }
}

类似的，stop方法也有一个异步的版本。如果你做清理工作要花点时间，就可以用它。

public class MyVerticle extends AbstractVerticle {

  public void start() {
    // Do something
  }

  public void stop(Future<Void> stopFuture) {
    obj.doSomethingThatTakesTime(res -> {
      if (res.succeeded()) {
        stopFuture.complete();
      } else {
        stopFuture.fail();
      }
    });
  }
}

提示：并不需要在stop方法中手动卸载某个verticle的子verticles(child verticles)，因为Vert.x会在父verticle被卸载时自动卸载它们。

Verticle的类型

有三种不同类型的verticle。

标准verticle(Standard Verticles)

这是最平常并有用的版本，它们会一直由同一个event loop线程执行。下一节里我们会更详细地讨论这个。

Worker Verticles

这一类由worker pool里的线程运行。绝不会有超过一个线程并发地执行单一实例。

多线程版(Multi-threaded) worker verticles

这些还是由worker pool里的线程运行，不过单一实例可以被多个线程并发执行。

标准verticle

标准verticle被创建的时候，它们会被指定给一个event loop线程，然后event loop会调用其start方法。当你从event loop调用任意核心API上可以接受handler的方法时，Vert.x保证那些handlers会由同样的event loop执行。

这意味着我们可以保证一个verticle实例里的所有代码都会在同一个event loop上执行（只要你不自己创建线程并调用它！）。

这同样意味着可以像单线程应用那样来写所有代码，至于多线程并发和扩展的问题交给Vert.x就可以了。不需要有同步和易变性（volatile）的困扰，这样你也可以避免‘传统的’手写多线程应用中普遍会碰到的状况，譬如竞争条件（race conditions）和死锁（deadlock）。

Worker Verticles

worker verticle和标准verticle挺像的，不同点在于worker verticle由Vert.x的worker 线程池中的线程执行，而标准verticle由event loop执行。

worker verticle是为调用阻塞代码而设计的。它们不会阻塞任意的event loop。

如果你不想用worker verticle来执行阻塞代码，那也可以通过直接运行内联阻塞代码的方式（就是前文所述的executeBlocking）。

如果你想将某个verticle作为worker verticle部署，可以通过调用setWorker方法。

DeploymentOptions options = new DeploymentOptions().setWorker(true);
vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", options);

worker verticle实例绝不会被多个线程并发执行，但可以被不同线程在不同时候执行。

多线程版worker verticle

一个多线程版worker verticle就像普通的worker verticle一般，但它可以被不同线程并发执行。

警告：多线程版worker 线程是个高级特性，绝大多数应用对此并无需求。为了这些verticle的并发执行，你需要使用标准的Java多线程编程技能，小心地使verticles保持一致的状态。

以编程的方式部署verticle

你可以使用deployVerticle系列方法中的一个来部署verticle，只需要知道verticle的名称或者你自己创建一个verticle实例丢过去。

注意：部署verticle实例的方式是Java专有的。

Verticle myVerticle = new MyVerticle();
vertx.deployVerticle(myVerticle);

你也可以通过指定verticle的名称来部署。

verticle的实例化需要用到特定的VerticleFactory，verticle的名称就是用来查询这个特定的工厂类。

不同的语言有不同的工厂类，用来初始化verticle。原因多种多样，比如运行时从Maven加载服务或者获取verticles。

这样你可以部署任意以Vert.x支持的语言写就的verticle。

下面是一个部署不同种verticle的例子：

vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle");

// Deploy a JavaScript verticle
vertx.deployVerticle("verticles/myverticle.js");

// Deploy a Ruby verticle verticle
vertx.deployVerticle("verticles/my_verticle.rb");

从verticle的名称映射到verticle factory的规则

当使用名称部署verticle时，名称的作用是选出实际中用来实例化这个verticle的verticle factory。

verticle的名称可以有一个前缀：前缀是个字符串，后面紧跟着一个冒号；如果前缀存在将被用于查询对应的factory。
即：
js:foo.js // Use the JavaScript verticle factory
groovy:com.mycompany.SomeGroovyCompiledVerticle // Use the Groovy verticle factory
service:com.mycompany:myorderservice // Uses the service verticle factory

如果没有前缀，Vert.x会寻找后缀来查询factory。
即：
foo.js // Will also use the JavaScript verticle factory
SomeScript.groovy // Will use the Groovy verticle factory

如果前后缀都不存在，那么Vert.x会假定这是一个完全限定类名（FQCN）的Java verticle，并试着循此实例化。

Verticle Factories如何定位呢？

绝大多数verticle factories都是从类路径（classpath）中加载的，在Vert.x启动时注册。

同样地，如果你希望用编程的方式注册、注销verticle factories，那么有registerVerticleFactory和unregisterVerticleFactory可用。

等待部署完成

verticle的部署是异步进行的，可能完成的时候对部署方法的调用都已经返回一阵子了。

如果你想在部署完成时收到通知，可以在部署时指定一个完成处理器（completion handler）：

vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", res -> {
  if (res.succeeded()) {
    System.out.println("Deployment id is: " + res.result());
  } else {
    System.out.println("Deployment failed!");
  }
});

如果部署成功，此handler会收到一个字符串，这里面包含了部署的ID。

后面在你卸载这次部署的verticle时，会用到这个ID。

卸载部署的verticle

可以使用undeploy来卸载已部署的verticle。

卸载本身也是异步的。所以如果你想在完成的时候收到通知，处理方法同部署的时候：

vertx.undeploy(deploymentID, res -> {
  if (res.succeeded()) {
    System.out.println("Undeployed ok");
  } else {
    System.out.println("Undeploy failed!");
  }
});

指定verticle实例的数量

用verticle的名称部署时，可以指定verticle实例的数量：

DeploymentOptions options = new DeploymentOptions().setInstances(16);
vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", options);

这个特性在扩展到多核cpu上时很有帮助。比如你要部署一个web服务器的verticle，并且你的机器上有多个核心；为了这多个核心能充分发挥自己的光和热，你可以部署上多个实例。

给verticle传递配置参数

部署时可以将配置以JSON的形式传递给verticle：

JsonObject config = new JsonObject().put("name", "tim").put("directory", "/blah");
DeploymentOptions options = new DeploymentOptions().setConfig(config);
vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", options);

之后配置信息将可通过Context对象使用，或者直接使用config方法。

返回的配置是一个JSON对象，所以你可以像下面这样取数据：
System.out.println("Configuration: " + config().getString("name"));

在verticle中访问环境变量

环境变量和系统属性可以用Java API访问：

System.getProperty("prop");
System.getenv("HOME");

verticle隔离组（Verticle Isolation groups）

缺省情况下，Vert.x有一个扁平的类路径(flat classpath)，部署vertilce时，Vert.x会使用当前的类加载器（classloader）--而不是创建一个新的。多数情况下，这都是最简单、清晰、稳健的做法。

然而，有时候你可能想把某些verticle的部署与其他的隔离开来。

譬如，你想在同一个Vert.x实例中部署同一个verticle的不同版本，他俩还有着相同的类名；又或者你的两个不同verticle分别用到了同一个类库的不同版本。

使用隔离组时，你需要提供待隔离类的名称列表。方法setIsolatedClasses可以搞定这个事。传入的名称可以是类似com.mycompany.myproject.engine.MyClass这样的完全限定类名；还可以是类似com.mycompany.myproject.这样带通配符的，这会匹配到包com.mycompany.myproject*里的任意类和任意子包。

请注意唯有匹配到的类才会被隔离，其他的类仍然由当前的类加载器载入。

如果想从非主类路径中加载类和资源，那你可以用setExtraClasspath方法提供额外的类路径条目。

警告：使用这个特性要小心。类加载器们也可能带来一堆bug，使你的排错工作变得困难（译注：大家知道bug在英文里有虫子和计算机程序错误的意思；所以此处前面说虫子，后面说除错困难）。

这儿有个利用隔离组来隔离一个verticle的部署的例子。

DeploymentOptions options = new DeploymentOptions().setIsolationGroup("mygroup");
options.setIsolatedClasses(Arrays.asList("com.mycompany.myverticle.*",
                   "com.mycompany.somepkg.SomeClass", "org.somelibrary.*"));
vertx.deployVerticle("com.mycompany.myverticle.VerticleClass", options);

高可用性

部署verticle时可以打开高可用性（HA），在这样的上下文环境里，若某个Vert.x实例上的某个vertilce意外地挂掉，集群里的另一个Vert.x实例将会重新部署这个verticle。

以高可用性运行verticle时，只需要在命令行后面加上** -ha **：
vertx run my-verticle.js -ha

打开高可用性时，无需添加** -cluster **。

更多关于高可用性和配置的细节可以在下面的高可用性和故障转移（High Availability and Fail-Over）一节中找到。

从命令行运行verticles

将依赖添加到Vert.x核心包里，就能以正常方式在你的maven或gradle项目中直接使用Vert.x。

不过你也可以直接从命令行运行verticle。

为了达成这个目的，你要下载并安装好Vert.x的发布包，并将安装目录下的** bin 目录添加到 PATH 环境变量，同样要确保Java8 的JDK在 PATH **里。

注意：为了动态编译Java代码，JDK是必要的（言下之意，只装JRE是不够的）。

一切就绪，现在可以用** vertx run **运行verticle了。下面有几个例子：

# Run a JavaScript verticle
vertx run my_verticle.js

# Run a Ruby verticle
vertx run a_n_other_verticle.rb

# Run a Groovy script verticle, clustered
vertx run FooVerticle.groovy -cluster

至于Java verticle，甚至不需要编译你就可以直接运行它！
vertx run SomeJavaSourceFile.java

Vert.x会在运行前动态地编译它。这点在快速建立原型和演示时特别有用。不需要先设置Maven或Gradle就能开始了。

有关在命令行执行vertx时各种其他可用的选项的所有信息，只需要在命令行输入vertx即可获得。

退出Vert.x

Vert.x实例维护的进程不是守护进程（daemon threads），所以它们会阻止JVM退出。

如果你以嵌入的方式使用Vert.x，工作完成的时候，你可以调用close方法关闭它。

这样做会关闭所有内部线程池、其他的资源，并允许JVM退出。

上下文对象（The Context object）

Vert.x给handler提供事件、或者调用verticle的start/stop方法时，其执行状况都是与一个Context(上下文)联系在一起的。通常，这个context是一个与特定的event loop线程绑定的event-loop context。所以与此context相关的执行动作都发生在同一确定的event loop线程上。至于worker verticle和运行内联的阻塞代码时，会有一个worker context与之关联，这些动作都由worker 线程池里的线程运行。

利用getOrCreateContext方法，可以获得上下文环境：
Context context = vertx.getOrCreateContext();

如果当前线程已经存在一个context与之关联，它会重用这个context对象。否则会创建context的一个新实例。可以像下面这样测试下取到的context的类型：

Context context = vertx.getOrCreateContext();
if (context.isEventLoopContext()) {
  System.out.println("Context attached to Event Loop");
} else if (context.isWorkerContext()) {
  System.out.println("Context attached to Worker Thread");
} else if (context.isMultiThreadedWorkerContext()) {
  System.out.println("Context attached to Worker Thread - multi threaded worker");
} else if (! Context.isOnVertxThread()) {
  System.out.println("Context not attached to a thread managed by vert.x");
}

在你拿到一个context对象后，可以在此context里异步地运行代码。换句话说，你提交的任务最终会运行在同样的context里：

vertx.getOrCreateContext().runOnContext( (v) -> {
  System.out.println("This will be executed asynchronously in the same context");
});

当有数个handler运行在同一context里时，它们可能会希望共享一些数据。context对象提供了存取共享在上下文里数据的方法。例如，你要传递数据过去做点事，可以用runOnContext方法：

final Context context = vertx.getOrCreateContext();
context.put("data", "hello");
context.runOnContext((v) -> {
  String hello = context.get("data");
});

context对象也允许你通过config方法访问verticle的配置信息。去看看** 给verticle传递配置 **一节吧，你将获得关于此项配置的更多细节。

定期、延时执行

在Vert.x里，延时或定期执行是很普遍的。

在标准verticle里，你不能以使线程休眠的方式引入延迟；这样干会阻塞event loop线程。

取而代之的是Vert.x定时器，定时器分为一次性（one-shot）和周期性（periodic）的。下面我们会分别讨论。

一次性定时器

一段确定的延时过后，一次性定时器将调用事件handler，度量衡是毫秒。

设置一个触发一次的定时器用到setTimer方法，它有两个参数：延时和一个handler。

long timerID = vertx.setTimer(1000, id -> {
  System.out.println("And one second later this is printed");
});

System.out.println("First this is printed");

返回值是定时器的ID（long类型），它具有唯一属性。之后你可以用这个ID来取消定时器。这个handler也会收到定时器的ID。

周期性定时器

类似的，利用setPeriodic方法可以设置一个定期触发的定时器。

初始的延迟值就是周期间隔。

返回值与一次性定时器一样，此处不再赘述。

定时器的事件handler的参数也与一次性定时器一致：

记住，定时器会定期触发。如果你的定期处理需要耗费大量时间，你的定时器事件可能会连续运行甚至糟糕到堆积在一起。

在这种情况下，你应该考虑转而使用setTimer。一旦你的处理完成了，你可以再设置下一个定时器。

long timerID = vertx.setPeriodic(1000, id -> {
  System.out.println("And every second this is printed");
});

System.out.println("First this is printed");

取消定时器

像下面这样，调用cancelTimer方法，指定定时器ID，即可取消周期定时器。

verticle里的自动清理（Automatic clean-up in verticles）

如果你是在verticle内部创建的定时器，那么verticle被卸载时，这些定时器将被自动关闭。

事件总线(The Event Bus)

event bus是Vert.x的神经系统。

每个Vert.x实例都拥有单独的一个event bus实例，你可以通过eventBus方法得到它。

应用的不同部分，不管是否在同一个Vert.x实例里，即使是不同语言编写的，都可以通过event bus彼此交流。

甚至浏览器里运行的的客户端JavaScript也可以通过同一个event bus相互通信。

event bus在多个服务器和多个浏览器间形成了一个分布式的点对点消息系统。

event bus支持发布/订阅(publish/subscribe)、点对点、请求-响应(request-response)这三种消息模式。

event bus的API很简单，主要包括注册handlers，注销handlers，发送和发布消息。

基本概念

寻址(Addressing)

消息通过event bus发送到某个地址(address)。

Vert.x没有花哨的令人困扰的寻址方案。Vert.x里地址就是字符串。任意字符串都有效。不过使用某种命名策略还是很明智的，例如使用分隔符限定命名空间。

这里是一些有效的地址：europe.news.feed1, acme.games.pacman, sausages, and X。

处理器(Handlers)

消息由handlers接收，所以你需要把handler注册到地址上。

同一个地址可以注册多个不同的handler。

某个handler也可以被注册在多个不同的地址上。

发布/订阅消息(Publish / subscribe messaging)

event bus支持发布(publishing)消息。

消息被发布到某个地址，这意味着把消息分发到注册在此地址上的所有handlers。

这就是我们很熟悉的发布/订阅模式。

点对点和请求-响应(Point to point and Request-Response messaging)

event bus也支持点对点消息。

当消息被发送到某个地址，Vert.x会把消息路由给注册在此地址上的某个handler。

如此此地址上注册了超过一个handler，Vert.x将会通过一个不严格的轮询算法(non-strict round-robin algorithm)从中选择一个。

在点对点的消息机制中，发消息时可以选择指定一个应答handler(reply handler)。

当有接收者收到消息并处理后，接收者可以选择是否答复此消息。如果选择答复，上述的reply handler将被调用。

发送者收到消息回应后，同样可以做出回应。这可以无限地重复下去，并允许两个不同的verticle间形成对话。

这种通用的消息模式称为请求-响应模式。

尽力分发(Best-effort delivery)

Vert.x会尽最大的努力分发消息，绝不会有意丢弃某些消息。这被称为尽力分发。

然而，在event bus部分或全部失效的情况下，消息还是有可能丢失。

如果你的应用很关心这一点，那么编码时应该注意使你的handler是幂等的(be idempotent)，并且发送方应该在恢复后尝试重新发送消息。

消息的类型

任何的基本类型/简单类型，字符串或者buffers都可以被当成消息发送出去。

但是Vert.x里通常使用JSON格式的消息。

在Vert.x支持的语言里，创建、读取、解析JSON都很容易，所以它就成了Vert.x上的通用语(lingua franca)。

当然了，并不是必须使用JSON。

event bus是很灵活的，支持在其上发送任意专有的对象。你只需为此定义一个编解码器(codec)。

The Event Bus API

下面让我们来看看API。

获取event bus对象

可以像下面这样拿到event bus对象的引用：
EventBus eb = vertx.eventBus();

每个Vert.x实例有唯一的event bus实例。

注册handlers

注册handler最简单的方法是用consumer方法。看例子：

EventBus eb = vertx.eventBus();

eb.consumer("news.uk.sport", message -> {
  System.out.println("I have received a message: " + message.body());
});

当你的handler收到一条消息时，handler会被调用，而消息(message)会作为参数传递过去。

consumer方法会返回一个MessageConsumer实例。

这个对象可以用来注销handler，或将handler当作流(stream)来使用。

或者你也可以用consumer方法得到一个未设置handler的MessageConsumer 对象，随后再设置handler：

EventBus eb = vertx.eventBus();

MessageConsumer<String> consumer = eb.consumer("news.uk.sport");
consumer.handler(message -> {
  System.out.println("I have received a message: " + message.body());
});

当在一个集群event bus上注册了handler时，完成在集群上每个节点的注册需要花点时间。

如果你想在完成时得到通知，你可以在MessageConsumer 对象上注册一个completion handler。

consumer.completionHandler(res -> {
  if (res.succeeded()) {
    System.out.println("The handler registration has reached all nodes");
  } else {
    System.out.println("Registration failed!");
  }
});

注销handlers

注销handler可以通过调用unregister方法完成。

在集群event bus做这件事时，同样要花点时间等其传播到各个节点，所以你也可以通过unregister方法得到通知。

consumer.unregister(res -> {
  if (res.succeeded()) {
    System.out.println("The handler un-registration has reached all nodes");
  } else {
    System.out.println("Un-registration failed!");
  }
});

发布消息

发布一个消息只需简单地调用publish方法，指定要发往的地址。
eventBus.publish("news.uk.sport", "Yay! Someone kicked a ball");

这个消息会被分发到注册在地址 news.uk.sport 上的所有handlers。

发送消息

发送消息的结果是注册在此地址上的handler只有一个会收到消息。这是点对点的消息模式。

你可以用send方法发送消息:
eventBus.send("news.uk.sport", "Yay! Someone kicked a ball");

设置消息头(Setting headers on messages)

event bus 上传输的消息也可以包含一些消息头(headers)。

可以在发送/发布消息时指定一个DeliveryOptions对象来做这件事：

DeliveryOptions options = new DeliveryOptions();
options.addHeader("some-header", "some-value");
eventBus.send("news.uk.sport", "Yay! Someone kicked a ball", options);

消息的顺序

Vert.x会将消息以发送者送出的顺序分发给handler。

消息对象

你在handler里收到的消息是一个Message对象。

消息的body就是发送过来的对象。

消息头可以通过headers方法得到。

消息/发送回应的知识点(Acknowledging messages / sending replies)

使用send方法时event bus会尝试把消息发送到注册在event bus上的MessageConsumer对象。

某些情况下，发送方可能想知道消息已经被接收并处理了。

为了让发放方了解消息已被处理，consumer可以通过调用reply方法给予回应。

如果这么做了，那么发送方将会收到一个回应，并且回应handler将被调用。看下面这个例子：
接收方：

MessageConsumer<String> consumer = eventBus.consumer("news.uk.sport");
consumer.handler(message -> {
  System.out.println("I have received a message: " + message.body());
  message.reply("how interesting!");
});

发送方：

eventBus.send("news.uk.sport", "Yay! Someone kicked a ball across a patch of grass", ar -> {
  if (ar.succeeded()) {
    System.out.println("Received reply: " + ar.result().body());
  }
});

回应可以带一个消息体，你可以在其中放置一些有用的信息。

“处理”实际上是由应用程序定义的，其中会发生什么完全依赖于consumer做了什么；Vert.x的event bus并不知道也不关心这些。

例如：

• 一个简单的消息consumer，它实现了返回当天时间的服务；可以确认回应的消息体中包含了这个时间。
• 一个实现了持久化队列的消息consumer，如果消息被成功地持久化在存储中可以确认是true，反之则为false。
• 一个处理订单的消息consumer，当订单被成功处理时，它可以从数据库里被删掉，这时候可以确认是true。

指定超时时间的发送(Sending with timeouts)

在发送一个带回应handler的消息时，可以在DeliveryOptions对象里指定超时的时间。

如果在这段时间里没有收到回应，回应handler将被调用，并以失败结束。

缺省的超时时间是30秒。

发送失败(Send Failures)

消息发放也可能因为其他原因失败，包括：

• 消息发送到的地址没有handler可用。
• 接收方显示地调用fail方法返回了失败的信息。

所有的情况下回应的handler都会被调用，并返回特定的错误。

消息编解码器(Message Codecs)

只要你定义并注册了相关的message codec，就可以在event bus上发送任意的对象。

当发送/发布消息时，你需要在DeliveryOptions对象上指定codec的名称：

eventBus.registerCodec(myCodec);

DeliveryOptions options = new DeliveryOptions().setCodecName(myCodec.name());

eventBus.send("orders", new MyPOJO(), options);

如果你想一直使用同一个codec，可以将它注册成缺省的codec，这样后面就不用每次发消息时再专门指定：

eventBus.registerDefaultCodec(MyPOJO.class, myCodec);

eventBus.send("orders", new MyPOJO());

unregisterCodec方法可以用来注销codec。

消息codec并不总是对同样的类型进行编码、解码。例如，你可以写一个codec用来发送MyPOJO类，而当消息送达handler时，可以是MyOtherPOJO类。

集群event bus

event bus并不只是存在于单一的Vert.x实例中。将多个Vert.x实例组成集群后，可以形成一个单独的，分布式的event bus。

以编程实现集群

如果你以编码的方式创建了Vert.x实例，将Vert.x实例配置成集群式的即可得到集群event bus；

VertxOptions options = new VertxOptions();
Vertx.clusteredVertx(options, res -> {
  if (res.succeeded()) {
    Vertx vertx = res.result();
    EventBus eventBus = vertx.eventBus();
    System.out.println("We now have a clustered event bus: " + eventBus);
  } else {
    System.out.println("Failed: " + res.cause());
  }
});

当然你应该确保classpath中有一个ClusterManager的实现，例如缺省的HazelcastClusterManager。

命令行里实现集群

你可以在命令行里运行集群vertx：
vertx run my-verticle.js -cluster

verticle的自动清理

如果你在verticle内部注册了event bus handlers，当这些verticle被卸载时handlers将被自动注销。

JSON

与其他语言不同，Java对JSON并没有提供头等的支持；所以我们提供了两个类，使得JSON的处理容易些。

JSON 对象

JsonObject类用来表示JSON对象。

JSON对象基本可以认为是个map，键是字符串，而值可以是JSON支持的类型中的一种(字符串、数字、布尔型)。

JSON对象也支持null 值。

创建JSON对象

默认的构造器可以创建一个空的JSON对象。

你也可以从JSON格式的字符串创建一个JSON对象：

String jsonString = "{\"foo\":\"bar\"}";
JsonObject object = new JsonObject(jsonString);

向JSON对象中添加条目

put方法可以用于往JSON对象中添加条目。

put方法支持流式API：

JsonObject object = new JsonObject();
object.put("foo", "bar").put("num", 123).put("mybool", true);

从JSON对象中取值

可以使用类似getXXX方法从JSON对象中取值，例如：

String val = jsonObject.getString("some-key");
int intVal = jsonObject.getInteger("some-other-key");

将JSON对象编码为字符串

encode方法用来将JSON对象转换为字符串。

JSON 数组

JsonArray类用来表示JSON 数组。

一个JSON 数组是一些值(字符串、数字或者布尔型)组成的序列。

JSON 数组也可以包括null 。

创建JSON 数组

默认的构造器可以创建一个空的JSON 数组。

可以从JSON格式的字符串创建JSON 数组：

String jsonString = "[\"foo\",\"bar\"]";
JsonArray array = new JsonArray(jsonString);

往JSON数组中添加元素

add方法：

JsonArray array = new JsonArray();
array.add("foo").add(123).add(false);

从JSON 数组中取值

类似下面这样：

String val = array.getString(0);
Integer intVal = array.getInteger(1);
Boolean boolVal = array.getBoolean(2);

将JSON 数组转换为字符串

使用encode即可。

Buffers

Vert.x中大量使用buffers传输数据。

buffer是一个可以读写的字节序列，超出其容量时，它会自动扩展。可以将其看成一个智能的字节数组。

创建buffers

可以使用静态方法Buffer.buffer创建buffers。

buffer可以由字符串或字节数组初始化，当然，空的buffer也是允许的。

这里有些例子。空buffer：
Buffer buff = Buffer.buffer();

字符串初始化的buffer，这里的字符串将使用UTF-8编码成buffer。
Buffer buff = Buffer.buffer("some string");

或者你可以指定编码：
Buffer buff = Buffer.buffer("some string", "UTF-16");

从字节数组创建：

byte[] bytes = new byte[] {1, 3, 5};
Buffer buff = Buffer.buffer(bytes);

如果你知道将会有多少数据待写入，可以在创建buffer时指定buffer的尺寸。这样buffer创建时就会分配这么多内存，这在效率上要优过边写入边扩容。

注意，这样创建的buffer仍然是空的(empty)。创建时并不会有0填充于其中。
Buffer buff = Buffer.buffer(10000);

写buffer

写入buffer有两种方式：附加(appending)、随机存取(random access)。这两种方式下，buffer都会自动扩容。不会产生**IndexOutOfBoundsException **异常。

Appending to a Buffer

往buffer上附加信息，可以使用**appendXXX **系列方法。有适合各种类型的append方法。

append系列方法的返回值就是buffer本身，所以适用链式写法：

Buffer buff = Buffer.buffer();

buff.appendInt(123).appendString("hello\n");

socket.write(buff);

Random access buffer writes

你也可以通过一系列**setXXX **方法在指定的索引处写入数据。set系列方法的第一个参数都是索引值。

buffer会自动扩容的。

Buffer buff = Buffer.buffer();

buff.setInt(1000, 123);
buff.setString(0, "hello");

读buffer

**getXXX **系列方法用来从buffer中读取数据。get系列方法的第一个参数也是指示从哪开始读的索引值。

Buffer buff = Buffer.buffer();
for (int i = 0; i < buff.length(); i += 4) {
  System.out.println("int value at " + i + " is " + buff.getInt(i));
}

使用无符号数

可以使用**getUnsignedXXX、appendUnsignedXXX、setUnsignedXXX **系列方法读写buffer。当你在为网络协议实现编解码器时，如果想将带宽消耗优化到极致，这个特性能帮上忙。

下面这个例子里，使用一个字节在指定位置写入200：

Buffer buff = Buffer.buffer(128);
int pos = 15;
buff.setUnsignedByte(pos, (short) 200);
System.out.println(buff.getUnsignedByte(pos));

控制台将显示‘200’。

buffer的长度

length方法可以获得buffer的长度。buffer的长度是最大的索引值+1。

复制buffer

使用copy方法。

将buffer分片(slicing buffers)

slice方法用来将buffer分片，切分出来的新buffer与原buffer共享缓存区。

buffer重用

在buffer被写入socket或类似地方后，它就不能再被使用了。