/

Generating Taxi from source

Instantiate Taxi from its original source

Java & Kotlin

You can generate Taxi models and services from Java and Kotlin.

Examples are shown in Kotlin throughout this guide, as it makes for shorter code snippets. However, the same approaches will work for Java too.

@DataType & @Namespace

@Namespace("demo")
@DataType
data class Person(...)  // generates demo.Person

@DataType("demo.Person")
data class Person(...)  // generates demo.Person

@DataType is the main annotation to indicate that a class should have a Taxi schema generated.

Namespaces may be defined either through the @Namespace("foo.bar") annotation, or within a @DataType directly.

If the namespace isn't provided through either approach, the package name is used.

Fields on types are exported. By default, the corresponding primitive type in Taxi is used. However, the output type can be customized by specifying the type in a @DataType annotation on the field, which will result in a Type alias within Taxi being generates.

@DataType("demo.Client")
data class Client(@field:DataType("demo.ClientId") val clientId: String,
        val clientName: String,
        @field:DataType("isic.uk.SIC2008") val sicCode: String
)

TaxiGenerator().forClasses(Client::class.java).generateAsStrings()

// Generates:
namespace demo {
    type Client {
        clientId : ClientId as String
        clientName : String
        sicCode : isic.uk.SIC2008
    }
}

namespace isic.uk {
    type alias SIC2008 as String
}

If you're working in Kotlin, using typealias with the @DataType annotation is recommended over annotating fields directly, as it leads to more readable & maintainable code.

Support for Kotlin Type Aliases

Type aliases can be directly annotated with the @DataType annotation.

package com.foo.bar

@DataType
data class Bus(val passengers: Passengers)

@DataType
typealias Passengers = List<Person>

@DataType("foo.Person")
data class Person(val name: PersonName)

@DataType("foo.PersonName")
typealias PersonName = String

TypeAliasRegister.registerPackage("com.foo.bar")
val taxiDef = TaxiGenerator().forClasses(Bus::class.java).generateAsStrings()

// Generates:
model Bus {
    passengers : Passengers
}

model Person {
    name : PersonName
}

type PersonName inherits String
type alias Passengers as Person[]

If using the @DataType against a Kotlin type alias, you need to declare the package(s) at startup.

This is as simple as:

import lang.taxi.generators.kotlin.TypeAliasRegister

TypeAliasRegister.registerPackage("com.foo.bar")

Any annotated type aliases in the provided package will be discovered and have their names generated correctly.

Constraints

Constraints are supported via the @Constraint annotation.

@DataType("orbital.Money")
data class Money(val amount: BigDecimal, val currency: String)

@ParameterType
@DataType("orbital.SomeRequest")
data class SomeRequest(
        @Constraint("currency == 'USD'")
        val amount: Money)

TaxiGenerator().forClasses(Money::class.java, SomeRequest::class.java).generateAsStrings()

// Generates:
namespace orbital {
     parameter type SomeRequest {
        amount : Money(currency == "USD")
     }
     type Money {
        amount : Decimal
        currency : String
     }
}

Parameter Type

Parameter types are indicated through the @ParameterType annotation.

Services & Operations

Services and Operations are exposed via the @Service and @Operation annotations respectively.

@Service("taxi.example.PersonService")
class MyService {
    @Operation
    fun findPerson(@DataType("taxi.example.PersonId") personId: String): Person {
    }
}

TaxiGenerator().forClasses(MyService::class.java, Person::class.java).generateAsStrings()

// Generates:
namespace taxi.example {
    type Person {
        personId : PersonId as String
    }
    service PersonService {
        operation findPerson(PersonId) : Person
    }
}

Operations may customize the generated name of operation parameters through the @Parameter annotation:

@Operation
fun findPerson(@Parameter(name = "personId") id: String): Person ...

Service constraints & contracts

Constraints on parameters are defined by adding constraints to the @Parameter annotation.

Contracts for operations are defined on the method, using the @ResponseContract annotation.

@Service("taxi.example.MoneyService")
class MyService {
    @Operation
    @ResponseContract(basedOn = "source",
            constraints = ResponseConstraint("currency = targetCurrency")
    )
    fun convertRates(@Parameter(constraints = Constraint("currency = 'GBP'")) source: Money, @Parameter(name = "targetCurrency") targetCurrency: String): Money {
        TODO("Not a real service")
    }
}

TaxiGenerator().forClasses(MyService::class.java)

// Generates
namespace taxi.example

type Money {
    currency : Currency as String
    value : MoneyAmount as Decimal
}
service MoneyService {
    operation convertRates( Money( currency = "GBP" ),
        targetCurrency : String ) : Money( from source, currency = targetCurrency )
}

Taxi Generator customisation & extensions

Taxi's generator can be customized, adding additional annotations or modifying the tree structure before source is output.

The most common scenario here is to provide extensions to modify how services are generated. However, you can inject an entirely separate TypeMapper and ServiceMapper for complete control over the generation process. Take a look at TaxiGenerator to get started.

ServiceMapperExtension and OperationMapperExtension provide the ability to modify the way services are generated, injecting custom metadata (eg., to describe HTTP operations, or how to subscribe to a message bus).

The SpringMVC extensions (discussed below) give a good example of how to leverage this.

Spring MVC Extensions

java2taxi ships with extensions for Spring MVC, to add metadata about how services are discovered and invoked. They add the following features:

  • Support for mapping @GetMapping/@PostMapping etc to an HttpOperation() annotation on the output.
    • All HTTP methods are supported
    • Path variable substitution is supported
  • Support for mapping springs @RequestBody annotation to a corresponding @RequestBody annotation on the generated Taxi source.
  • Support for integration with service discovery from Spring Cloud's DiscoveryClient abstraction
Currently, the SpringMVC extensions are part of java2taxi. However, we expect to move these out to their own library in a future release.

Enable the extensions by configuring the TaxiGenerator as follows:

val taxiGenerator = TaxiGenerator(serviceMapper = DefaultServiceMapper(
    operationExtensions = listOf(SpringMvcHttpOperationExtension()),
    serviceExtensions = listOf(SpringMvcHttpServiceExtension(ServiceDiscoveryAddressProvider("mockService")))
))

Example usage:

@RequestMapping("/costs")
@Service("orbital.demo.CreditCostService")
class CreditCostService {
    @Operation
    @GetMapping("/interestRates/{clientId}")
    fun getInterestRate(@PathVariable("clientId") @DataType("orbital.demo.ClientId") clientId: String): BigDecimal = BigDecimal.ONE

    @PostMapping("/{clientId}/doCalculate")
    @Operation
    fun calculateCreditCosts(@PathVariable("clientId") @DataType("orbital.demo.ClientId") clientId: String, @RequestBody request: CreditCostRequest): CreditCostResponse = CreditCostResponse("TODO")
}

taxiGenerator.forClasses(CreditCostService::class.java).generateAsStrings()

// Generates:
namespace orbital.demo {

    type alias ClientId as String

     type CreditCostRequest {
        deets : String
    }

     type CreditCostResponse {
        stuff : String
    }

    @ServiceDiscoveryClient(serviceName = "mockService")
    service CreditCostService {
        @HttpOperation(method = "GET" , url = "/costs/interestRates/{orbital.demo.ClientId}")
        operation getInterestRate(  ClientId ) : Decimal
        @HttpOperation(method = "POST" , url = "/costs/{orbital.demo.ClientId}/doCalculate")
        operation calculateCreditCosts(  ClientId, @RequestBody CreditCostRequest ) : CreditCostResponse
    }
}

The tests give the best example of usage.

Maven / Gradle

The binaries are hosted by the Orbital team in their maven repository. Be sure to add the repository:

<repositories>
    <repository>
         <id>orbital</id>
         <url>https://repo.orbitalhq.com/release</url>
         <snapshots>
            <enabled>false</enabled>
         </snapshots>
      </repository>
</repositories>

Then grab the artifacts:

<!-- To generate Taxi, you need java2taxi -->
<dependency>
  <groupId>org.taxilang</groupId>
  <artifactId>java2taxi</artifactId>
  <version>${taxi.version}</version>
</dependency>

<!-- To annotate your models, you need the annotations package -->
<dependency>
  <groupId>org.taxilang</groupId>
  <artifactId>taxi-annotations</artifactId>
  <version>${taxi.version}</version>
</dependency>

Note - the current Taxi version is

Edit on Github