Vert.x for Ceylon

Vert.x is a lightweight, high performance application platform for the JVM that's designed for modern mobile, web, and enterprise applications.

The original Vert.x documentation explains how to use Vert.x. This Ceylon module is a port of the Vert.x API to Ceylon, with this API you can:

  • Embed Vert.x in a Ceylon application
  • Use the Vert.x API
  • Verticles are not covered by this API but are managed by the io.vertx.ceylon.platform Ceylon module.

Reference

The Event Bus

See io.vertx.ceylon.core.eventbus.

Shared Data

See io.vertx.ceylon.core.shareddata.

Buffers

Most data in Vert.x is shuffled around using instances of Buffer. We chose deliberately to use the Vert.x native type as it can easily used from Ceylon and a wrapper would complicate the bridge.

A Buffer represents a sequence of zero or more bytes that can be written to or read from, and which expands automatically as necessary to accomodate any bytes written to it. You can perhaps think of a buffer as smart byte array.

Creating Buffers

Create a new empty buffer:

value buff = Buffer();

Create a buffer from a String. The String will be encoded in the buffer using UTF-8.

value buff = Buffer("some-string");

Create a buffer from a String: The String will be encoded using the specified encoding, e.g:

value buff = Buffer("some-string", "UTF-16");

Create a buffer from a byte[] (using ByteArray)

ByteArray bytes = ...;
value buff = Buffer(bytes);   

Create a buffer with an initial size hint. If you know your buffer will have a certain amount of data written to it you can create the buffer and specify this size. This makes the buffer initially allocate that much memory and is more efficient than the buffer automatically resizing multiple times as data is written to it.

Note that buffers created this way are empty. It does not create a buffer filled with zeros up to the specified size.

value buff = Buffer(10000);

Writing to a Buffer

There are two ways to write to a buffer: appending, and random access. In either case buffers will always expand automatically to encompass the bytes. It's not possible to get an IndexOutOfBoundsException with a buffer.

Appending to a Buffer

To append to a buffer, you use the appendXXX methods. Append methods exist for appending other buffers, byte[], String and all primitive types.

The return value of the appendXXX methods is the buffer itself, so these can be chained:

value buff = Buffer();

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

Random access buffer writes

You can also write into the buffer at a specific index, by using the setXXX methods. Set methods exist for other buffers, byte[], String and all primitive types. All the set methods take an index as the first argument - this represents the position in the buffer where to start writing the data.

value buff = Buffer();

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

Reading from a Buffer

Data is read from a buffer using the getXXX methods. Get methods exist for byte[], String and all primitive types. The first argument to these methods is an index in the buffer from where to get the data.

Buffer buff = ...;
Integer i = buff.getInt(0);

Other buffer methods:

  • length(). To obtain the length of the buffer. The length of a buffer is the index of the byte in the buffer with the largest index + 1.
  • copy(). Copy the entire buffer

JSON

Whereas JavaScript has first class support for JSON, and Ruby has Hash literals which make representing JSON easy within code, things aren't so easy in Ceylon

A JSON object is represented by instances of Object. A JSON array is represented by instances of Array.

A usage example would be using a Ceylon verticle to send or receive JSON messages from the event bus.

value eb = vertx.eventBus();

value obj = Object { "foo"->"wibble", "age"->1000 };
eb.send("some-address", obj);

// ....
// And in a handler somewhere:

shared void handle(Message<Object> message) {
  print("foo is ``message.body["foo"]``");
  print("age is ``message.body["age"]``");
}

Delayed and Periodic Tasks

It's very common in Vert.x to want to perform an action after a delay, or periodically.

In standard verticles you can't just make the thread sleep to introduce a delay, as that will block the event loop thread.

Instead you use Vert.x timers. Timers can be one-shot or periodic. We'll discuss both

One-shot Timers

A one shot timer calls an event handler after a certain delay, expressed in milliseconds.

To set a timer to fire once you use the Vertx.setTimer() method passing in the delay and a handler

value timerId = vertx.setTimer(1000, (Integer timerId) => print("And one second later this is printed"));

print("First this is printed");

The return value is a unique timer id which can later be used to cancel the timer. The handler is also passed the timer id.

Periodic Timers

You can also set a timer to fire periodically by using the Vertx.setPeriodic() method. There will be an initial delay equal to the period. The return value of Vertx.setPeriodic() is a unique timer id (long). This can be later used if the timer needs to be cancelled. The argument passed into the timer event handler is also the unique timer id:

value timerId = vertx.setTimer(1000, (Integer timerId) => print("And every second this is printed"));

print("First this is printed");

Cancelling timers

To cancel a periodic timer, call the Vertx.cancelTimer() method specifying the timer id. For example:

value timerId = vertx.setTimer(1000, (Integer timerId) => print("Should not be printed"));

// And immediately cancel it

vertx.cancelTimer(timerID);

Or you can cancel it from inside the event handler. The following example cancels the timer after it has fired 10 times.

variable Integer count = 0;
vertx.setTimer {
  delay = 1000;
  void handle(Integer timerId) {
    print("In event handler ``count``");
    if (++count == 10) {
      vertx.cancelTimer(timerId);
    }
  }
};

Writing TCP Servers and Clients

See io.vertx.ceylon.core.net.

Flow Control - Streams and Pumps

See io.vertx.ceylon.core.stream.

Writing HTTP Servers and Clients

See io.vertx.ceylon.core.http.

Routing HTTP requests with Pattern Matching

See io.vertx.ceylon.core.http.

WebSockets

See io.vertx.ceylon.core.http.

SockJS

See io.vertx.ceylon.core.sockjs

SockJS - EventBus Bridge

See io.vertx.ceylon.core.sockjs

File System

See io.vertx.ceylon.core.file

By: Julien Viet
License: ASL2
Packages
io.vertx.ceylon.core
io.vertx.ceylon.core.eventbus

The Event Bus

The event bus is the nervous system of Vert.x.

io.vertx.ceylon.core.file

File System

Vert.x lets you manipulate files on the file system.

io.vertx.ceylon.core.http

Writing HTTP Servers and Clients

Writing HTTP servers

Vert.x allows you to easily write full featured, highly…

io.vertx.ceylon.core.net

Writing TCP Servers and Clients

Creating TCP servers and clients is very easy with Vert.x.

Net Server

io.vertx.ceylon.core.shareddata

Shared Data

Sometimes it makes sense to allow different verticles instances to share data in a safe way.

io.vertx.ceylon.core.sockjs

SockJS

WebSockets are a new technology, and many users are still using browsers that do not support them, or which…

io.vertx.ceylon.core.stream

Flow Control - Streams and Pumps

There are several objects in Vert.x that allow data to be read from and written to…

io.vertx.ceylon.core.util
Dependencies
ceylon.collection1.1.0
ceylon.io1.1.0
ceylon.json1.1.0
ceylon.promise1.1.0
ceylon.time1.1.0
com.fasterxml.jackson.annotations2.2.2
com.fasterxml.jackson.core2.2.2
com.fasterxml.jackson.databind2.2.2
io.netty4.0.20.Final
io.vertx.core2.1.2
io.vertx.platform2.1.2
java.base7
By: Julien Viet
Aliases
Chunkshared Chunk=> String|[String, String]|Buffer

A chunk of data, it can be:

  • A mere string
  • A string plus an encoding
  • A buffer
Entriesshared Entries=> {<String->String|{String+}>*}

Alias for the type for reading a loose list of entries

Functions
runshared void run()
By: Julien Viet
Interfaces
Registrationshared Registration

A registration, the completed promise is resolved when the registration is completed, the cancel() method can be used to cancel the registration.

Classes
ClientBaseshared ClientBase
Contextshared Context

Represents the execution context of a Verticle.

MultiMapshared MultiMap
NetworkBaseshared NetworkBase
ServerBaseshared ServerBase
Vertxshared Vertx

The control centre of the Vert.x Core API.

You should normally only use a single instance of this class throughout your application. If you are running in the Vert.x container an instance will be provided to you.

This class acts as a factory for TCP/SSL and HTTP/HTTPS servers and clients, SockJS servers, and provides an instance of the event bus, file system and shared data classes, as well as methods for setting and cancelling timers.

Create a new Vertx instance. Instances of this class are thread-safe.