This module allows you to read and write to streams, such as files, sockets and pipes.

It also defines character sets, for encoding and decoding bytes to strings, as well as buffers of bytes and characters for input/output.

See the ceylon.io package for usage examples.

By: Stéphane Épardaud
Packages
ceylon.io

This package lets you create FileDescriptor objects, which represent open streams, such as files, sockets, or pipes…

ceylon.io.buffer

This package contains all the required bits to deal with buffers of bytes and characters.

ceylon.io.buffer.impl
ceylon.io.charset

This package contains everything required to convert bytes to Strings according to character sets.

ceylon.io.impl
ceylon.io.readers

This package contains reader/writer objects that can read and write to/from FileDescriptor objects.

This package lets you create FileDescriptor objects, which represent open streams, such as files, sockets, or pipes. You can read and write bytes to those streams in synchronous or asynchronous ways, using ceylon.io.buffer.Buffer objects, and you can convert bytes to String objects using ceylon.io.charset.Charset objects.

Here's how you can get a Socket to a remote host in a blocking way:

// connect to example.com on port 80
value connector = newSocketConnector(SocketAddress("example.com", 80));
value socket = connector.connect();

Sample usage for reading all the available bytes from a remote socket in a blocking way:

void readResponse(Socket socket){
    // create a new decoder from ASCII bytes
    Decoder decoder = ascii.newDecoder();
    // read,decode it all, blocking
    socket.readFully((ByteBuffer buffer) decoder.decode(buffer));
    // print it all
    process.write(decoder.done());
}

Here's the same code, but in an asynchronous way, using a Selector object to treat read events:

void readResponseAsync(Socket socket){
    // create a new selector for reading from this socket
    Selector select = newSelector();
    // read, decode, print as we get data
    socket.readAsync(select, byteConsumerToStringConsumer(utf8, (String string) process.write(string)));
    // run the event loop
    select.process();
}

Here's how you could write a request to a Socket in a blocking way:

void writeRequest(String data, Socket socket) {
    // encode it in one go
    value requestBuffer = ascii.encode(data);
    // write it all, blocking
    socket.writeFully(requestBuffer);
}

Here's how you would write a request to a Socket in an asynchronous way:

void writeRequestAsync(String request, Socket socket){
    Selector select = newSelector();
    // encode and write as we can
    socket.writeAsync(select, stringToByteProducer(ascii, request));
    // run the event loop
    select.process();
}

Finally, here's how you can read and write asynchronously to the same socket:

void readAndWriteAsync(String request, Socket socket){
    Selector select = newSelector();
    // encode and write as we can
    socket.writeAsync(select, stringToByteProducer(ascii, request));
    // read, decode and print as we can
    socket.readAsync(select, byteConsumerToStringConsumer(utf8, (String string) process.write(string)));
    // run the event loop
    select.process();
}
By: Stéphane Épardaud
Methods
newOpenFile
shared OpenFile newOpenFile(Resource resource)

Creates a new OpenFile to read/write to the given resource.

See also: OpenFile
newSelector
shared Selector newSelector()

Returns a new selector object.

See also: Selector
newServerSocket
shared ServerSocket newServerSocket(SocketAddress? addr, Integer backlog)

Instantiates and binds a new server socket.

See also: ServerSocket
newSocketConnector
shared SocketConnector newSocketConnector(SocketAddress addr)

Creates a new SocketConnector to connect to the specified add.

See also: SocketConnector
Interfaces
FileDescriptor

Represents anything that you can read/write to, much like the UNIX notion of file descriptor.

This supports synchronous and asynchronous reading.

OpenFile
shared OpenFile

Represents a file object we can read/write to.

SelectableFileDescriptor

Represents a FileDescriptor that you can select. This means that you can register listeners for this file descriptor on a given Selector object that will be called whenever there is data available to be read or written without blocking the reading/writing thread.

Selector
shared Selector

Represents a listener that can listen for read/write/connect/accept events directly from the operating system.

You can register listeners for :

Those listeners will then be called by this selector when you invoke process until there are no more listeners.

Every listener can signal the selector object that it is no longer interested in notifications by returning false when invoked, except for connect listeners which are only notified once (since you can only connect a Socket once).

Listeners should be registered with:

You can instantiate new selectors with newSelector.

Socket
shared Socket

Represents a network socket.

Classes
ServerSocket
shared abstract ServerSocket

Represents a server socket: a socket open on the current host that accepts incoming connections from other hosts.

This supports synchronous and asynchronous modes of operations.

The server socket is bound immediately to the specified bindAddress (or to every local network interface if not set), but it will only accept incoming connections when you call accept or acceptAsync.

New server sockets are created with newServerSocket.

SocketAddress

Represents a internet socket address.

SocketConnector
shared abstract SocketConnector

Represents an object that you can use to connect to a remote host.

Both synchronous and asynchronous modes of operation are supported:

  • use connect to block until the socket is connected, or
  • use connectAsync to register a listener that will be invoked when the socket is connected.

You create new socket connectors with newSocketConnector.