Overview of Jnag

Summary

Jnag is a RPC library particularly designed for games.

It provides an Object Oriented data presentation layer to asynchronous messages. Its configuration is Annotation Driven, and the piece of code which encode and decode the messages is generated offline by the library.

The library is designed to be extensible to any language with inter-operability in mind.

How it works

Jnag is designed to do RPC (Remote Procedure Call) style messaging:

The library is divided into 2 parts, one part which is used at compilation time, and one part which is used at runtime. This is how the compilation part is working:

1. The user defines the communication protocol between your program hosts. Basically, he describes some procedure calls that a host can receive and handle. This is done via an "Interface Definition Language". Jnag use Java 5 as the IDL.
2. Then a tool from the Jnag library reads the protocol definition files, interprets them and generates a source code which will permit the sender of a message to send them and will permit the receiver of a message to receive them. Basically, the code generated is doing an encoding of the procedure calls into binary messages on the caller side, and is doing a decoding of the binary messages into procedure calls on the receiver side.

A part of the encoding/decoding code is not message-specific, this part is what constitutes the runtime part of the Jnag library.

Example of usage

This example shows briefly what needs to be done in order to use Jnag to send a message from a host A to a host B.

1. Definition of a message that the host A 'client' will send to the host B 'server':

   @NetworkInterface(HostKind.Server)
   public interface HostBService {
     public void doSomething(String a, int b, boolean c);
   }
   

2. The implementation of the service on the host B:

   public class HostBServiceImpl implements HostBService {
     public void doSomething(String a, int b, boolean c) {
       // Here on the host B, we do something.
     }
   }
   

3. Setup on the host A:

     JnagSession jnagSession = new JnagSessionImpl();
     // ... session setup things ...
   
     HostBService hostBServiceProxy = jnagSession.createProxy(HostBService.class);
   

4. Setup on the host B:

     JnagSession jnagSession = new JnagSessionImpl();
     // ... session setup things ...
   
     HostBServiceImpl hostBServiceImpl = new HostBServiceImpl();
     jnagSession.bind(hostBServiceImpl, HostBService.class);
   

5. The host A sends a message to the host B:

     hostBServiceProxy.doSomething("Isn't it great? :-)", 33, true);
   

And that's it.

Main Features

Some of the important features of Jnag:

• Easy to use

• Lightweight

The part of the library used at runtime is around 40kb.

• Non intrusive

To use Jnag doesn't require a special program architecture, and you don't have to refactor it if you want to stop using it.

• Pojo style

Calling a remote procedure via Jnag is just the same as calling a procedure on a local object.

• Object Oriented

In Jnag, you can call procedures on remote services (C style) as well as on remote object instances (Object Oriented style).

• Java style IDL

The Interface Definition Language (IDL) which is used to generate the encoders and decoders just look like classical java interfaces with a few annotations here and there. You don't have to learn one extra language or script, and you can write them confortably within you preferred Java IDE with all the code completion and code navigation features which come with it.

• Support for common data structure as parameter

Jnag can encode Java primitives, Arrays, Lists, Sets, Maps, and Enumerations.

• Support for object reference as parameter

Jnag can send some references of objects as argument to a remote host if those objects are remote objects. Other objects will be able to be passed by value via customer serialization in later releases.

• Subject-Observer binding framework

Jnag contains a small framework to easily and transparently bind together an object of an host A which is listening to an object on the host B. This is a special framework which needs some explanations, please see the documentation, you will love it.

• Caller Object injection

Jnag can generate asymetric interfaces for the receiver of a message and the senders. It is possible to have one of the procedure parameters only on the receiver side which identify the caller of a method. This is pretty useful for the programmer and is the fastest way to know who is calling your procedure.

• Efficient

The source code of the encoders and decoders of the procedure calls are generated offline and compiled with your application's source code. No CPU time is wasted interpreting message's encoding semantic at runtime.

• Readable

The generated source code of the encoders and decoders contain comments describing its content so that humans can read it and understand what it is doing.

• Scalable

Jnag has been specially designed with scalability in Mind. It is suitable for MMO games.

• Automatic Logging

Messages which are encoded and decoded can be logged automatically. The logger can be turned on and off without modifying your code at all.

• Platform Independent

Jnag only encode and decode data, the transfer of the data to the remote host is delegated to the user. This enables Jnag to be portable to any kind of platform.

• Topology agnostic

While having some features to support scalable star topology, Jnag is mainly operating on a P2P mode, enabling the use of any kind of network topology.

• Maven friendly

Jnag can be used (without Maven) as a classical library. However, for Maven users, Jnag can integrate the generation of the encoder and decoders within any Maven project via its own Maven plugin.

License

Jnag is free and open source. It is published under the LGPL license.