raphaeljolivet/java2typescript

A bridge between a Java model, REST services and Typescript definition


Continuous Integration (for last commit on any branch)

Purpose

Java2Typescript provides a bridge between a Java REST service definition and a Typescript client.

It enables you to expose a full DTO model and REST services API as a clean typescript definition file, thus enabling strong type-checking on the models of your application.

This project is composed of 3 modules :

• java2typescript-jackson: A Jackson module that generates typescript definition files for Java classes, using a Jackson ObjectMapper.
• java2typescript-jaxrs: An extension to java2typescript-jackson that takes a JAX-RS annotated java class and produces both :
• A Typescript definition file of the service (.d.ts), together with description of all needed DTO objects.
• An .js implementation of the above definition as a REST client stub.
• java2typescript-maven-plugin: A maven plugin to automate the generation of a .d.ts file and a .js implementation of REST services.
• A sample web application that demonstrate the usage of java2typescript

Big picture

Here is a schema of the workflow for a typical project using j2ts :

There are only two source files here :

• Server side: AppRest.java with annotated JAX-RS services
• Client side: App.ts

The detailed workflow is:

1. AppRest.java contains the annotated JAX-RS service definition
2. j2ts compiles the REST service definition into a .d.ts description file, and a .js file (runtime implementation)
3. App.ts imports and uses the .d.ts file
4. App.ts is compiled into a App.js file (by typescript compiler)

Usage

Please refer to the documentation of the maven plugin and the example below

Example

java2typescript handles all the HTTP REST standard itself, and provide REST services as vanilla Typescript methods, regardless of the HTTP method / mime to use.

Consider the following JAX-RS service

@Path( "/people" ) 
public interface PeopleRestService {
  
  
  @Produces( { MediaType.APPLICATION_JSON } )
  @GET
  public Collection< Person > getPeoples( @QueryParam( "page") @DefaultValue( "1" ) final int page ) {
    return peopleService.getPeople( page, 5 );
  }

  @Produces( { MediaType.APPLICATION_JSON } )
  @Path( "/{email}" )
  @GET
  public Person getPeople( @PathParam( "email" ) final String email ) {
    return peopleService.getByEmail( email );
  }
}

The maven plugin will produce the following typescript definition file :

export module People {

export interface PeopleRestService {
    getPeopleList(page: number): Person[];
    getPeople(email: string): Person;
}

export interface Person {
    email: string;
    firstName: string;
    lastName: string;
}

export var rootUrl: string;
export var peopleRestService: PeopleRestService;
export var adapter: (httpMethod: string, path: string, getParams: Object, postParams: Object, body: any)=> void;
}

The module People contains both the definitions of the DTO Person and the service PeopleRestService. It also provides 3 properties :

• rootURL : URL of the service : Should be set before usage
• peopleRESTService : An instance of the service
• adapter : An adapter for REST service call. Set to Jquery adapter by default.

Then, in your application, you can call the service like so:

/// <reference path="People.d.ts" />
import p = People;
import Person = p.Person;
import prs = p.peopleRestService;

p.rootUrl = "http://someurl/root/";

var personList : Person[] = prs.getPeopleList(1);
var onePerson : Person = prs.getPeople("rrr@eee.com");

Don't forget to import the generated file People.js in the final HTML page.

Installation

To install the library using Maven, add the JitPack repository and java2typescript dependency:

...
<repositories>
  <repository>
      <id>jitpack.io</id>
      <url>https://jitpack.io</url>
  </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>com.github.raphaeljolivet.java2typescript</groupId>
        <artifactId>java2typescript-maven-plugin</artifactId>
        <version>v0.3.1</version><!-- see notes bellow to get either snapshot or specific commit or tag or other version -->
    </dependency>
</dependencies>
...

Note, artifacts for this project are built automatically by JitPack based on the github repository.

Note, if You are only interested in generating TypeScript definitions from Java classes, You can use java2typescript-jackson instead of java2typescript-maven-plugin as the artifact id.

Note, version can be replaced with

• either any released version of this project ()
• or any git tag of this project
• or any git commit hash
• or with master-SNAPSHOT - to indicate the latest commit of master branch (NB! Dependency managers, such as Maven cache SNAPSHOTs by default, see JitPack documentation)

Licence

This project is licenced under the Apache v2.0 Licence

Credits

Jackson module is inspired from the jsonSchema module