Basic Tutorial (Java)

This tutorial introduces how CBOT can be used in Java -language.

Installation

Check newest version.

Concepts

The examples use of s library with three concepts: Author, Book and Catalog. These concepts are defined in simplified manner as follows:

package example.tutorial;

import java.time.LocalDate;

public class Author {
  private String name;
  private LocalDate birthdate;
}

public class Book {
  private String title;
  private String isbn;
  private Author author;
  private Integer publicationYear;
}

public class Catalog {
  private String genre;
  private List<Book> books;
  private Set<Author> authors;
}

Untyped Example

This example demonstrates a typical JSON-like behavior where sender does not have any fixed model in use (just plain JSON-objects).

Next, let's define some values:

var isaac = new Author();

isaac.setName("Isaac Asimov");
isaac.setBirthdate(LocalDate.of(1920, 1, 2));

var foundation = new Book();

foundation.setTitle("Foundation");
foundation.setIsbn("978-0-394-51330-7");
foundation.setPublicationYear(1951);
foundation.setAuthor(isaac);

var iRobot = new Book();

iRobot.setTitle("I, Robot");
iRobot.setIsbn("978-0-394-51331-4");
iRobot.setPublicationYear(1950);
iRobot.setAuthor(isaac);

var catalog = new Catalog();

catalog.setGenre("Science Fiction");
catalog.setBooks(Arrays.asList(foundation, iRobot));
catalog.setAuthors(new HashSet<>(Arrays.asList(isaac)));

Cbot instance

To serialize something, you need an instance of Cbot. Note that you should always create just one instance for each model/usage and use it globally. The Cbot instance is thread-safe.

The simplest version is created as follows:

import fi.sisujs.cbot.Cbot;

var cbot = Cbot.getInstance();

Usage

Now we can serialize an object to a string and vice versa:

var msg = cbot.serialize(foundation);
Book book = cbot.deserialize(msg, Book.class);

Getting a collection of objects

If the sender would be sending a list of Book-objects it would be serialized as:

List<Book> books = cbot.deserializeList(msg, Book.class);

Using Untyped Model

Adding Untyped Model creates an opportunity to reduce message size by sharing common static keys by both sender and receiver. This mode is initialized as follows:

var cbot = Cbot.getInstance(OptionsBuilder
  .create()
  .withStaticKeys(List.of(
    "name",
    "birthdate",
    "title",
    "isbn",
    "author",
    "publicationYear",
    "books",
    "genre",
    "authors"
  )).build());

Even though CBOT is now instantiated with shared static keys, that does not prevent from creating new Key-ID Pairs when needed during serialization. The instance can now be used in the same way as in previous example.

Note that in this mode, both parties must be configured in the same way, otherwise deserialization will fail.

Typed Example: Library

This example employs the usage of Typed Model

Namespace(s)

The first step is to create a namespace which differentiates classes in to usable global groups:

import fi.sisujs.cbot.model.Namespace;

var ns = Namespace.of("tutorial", "example.tutorial");

Here a Java-package example.tutorial is assigned with namespace tutorial.

Cbot instance

Next a proper Cbot-instance is created as follows:

var cbot = Cbot.getInstance(
  OptionsBuilder
    .create()
    .withNamespaces(List.of(ns))
    .build());

So, instead of adding static keys, I've added the namespace to it.

Usage

Next we can serialize and deserialize a catalog:

var msg = cbot.serialize(catalog);
var deserialized = (Catalog) cbot.deserialize(msg);

The difference here from the untyped example is that you no longer need to specify the root class for the deserialization process. Instead, the protocol already knows it and can infer the correct type, making a simple cast sufficient.

This behavior allows more flexibility in handling messages, as their types are no longer bound to a specific one. For example, you could use a superclass or an interface as the root type, without needing to concern yourself with the concrete type.

API Documentation