Cask Operations

This section will show you how Cask Generates Service operations.

Introduction

Cask uses field annotations when generating service operations for the given type.

Consider this example:

type TransactionEventDateTime inherits Instant
type OrderId inherits String
model Order {
@Id
orderId: OrderId
instrumentId: String
price: Decimal
@Between
orderDateTime : TransactionEventDateTime( @format ="MMM dd, yyyy HH:mm:ss")
}

In the above case, cask generates two methods for a model with four fields.

@ServiceDiscoveryClient(serviceName = "cask")
service OrderCaskService {
@HttpOperation(method = "GET" , url = "/api/cask/findSingleBy/Order/orderId/{id}")
operation findSingleByOrderID( @PathVariable(name = "id") id : OrderId ) : Order( OrderId = id )
@HttpOperation(method = "GET" , url = "/api/cask/Order/orderDateTime/Between/{start}/{end}")
operation findByOrderDateTimeBetween (
@PathVariable(name = "start") start : TransactionEventDateTime,
@PathVariable(name = "end") end : TransactionEventDateTime
) : Order[]( TransactionEventDateTime >= start, TransactionEventDateTime < end )
}

This is because only orderId and orderDateTime fields are annotated with @Id and @Between.

Supported annotations

@Id

Adding @Id on top of a field declaration:

namespace vyne.examples {
type OrderId inherits String
model Order {
@Id
orderId: OrderId
}
}

will result in the following operation being generated:

import vyne.examples.OrderId
import vyne.examples.Order
namespace vyne.casks.vyne.examples {
@ServiceDiscoveryClient(serviceName = "cask")
service OrderCaskService {
@HttpOperation(method = "GET" , url = "/api/cask/findSingleBy/vyne/examples/Order/orderId/{id}")
operation findSingleByOrderID(
@PathVariable(name = "id") id : vyne.examples.OrderId
) : vyne.examples.Order( vyne.examples.OrderId = id )
}
}

This is expected to return a single result, but this is not enforced during ingestion. Behaviour for how matches of mulitple records is defined in configuration. See this section of Configuration.

@PrimaryKey

Defining a primary key on models will generate a corresponding primary key on the database columns. The resulting operation is the same as generated for @Id, but ingestion behaviour is changed to UPSERT rather than INSERT.

@Before

Adding @Before on top of field declaration:

type alias MaturityDate as Date
type TransactionEventDateTime inherits Instant
type OrderWindowSummary {
@Before
maturityDate: MaturityDate
@Before
orderDateTime : TransactionEventDateTime( @format = "yyyy-MM-dd HH:mm:ss.SSSSSSS")
}

will result in the following operations being generated:

import OrderWindowSummary
import MaturityDate
import TransactionEventDateTime
namespace vyne.casks {
@ServiceDiscoveryClient(serviceName = "cask")
service OrderWindowSummaryCaskService {
@HttpOperation(method = "GET" , url = "/api/cask/OrderWindowSummary/maturityDate/Before/{before}")
operation findByMaturityDateBefore(
@PathVariable(name = "before") before : MaturityDate
) : OrderWindowSummary[]( MaturityDate < before )
@HttpOperation(method = "GET" , url = "/api/cask/OrderWindowSummary/orderDateTime/Between/{start}/{end}")
operation findByOrderDateTimeBefore(
@PathVariable(name = "before") before : TransactionEventDateTime
) : OrderWindowSummary[]( TransactionEventDateTime < before )
}
}

@After

Adding @After on top of field declaration:

type alias MaturityDate as Date
type TransactionEventDateTime inherits Instant
type OrderWindowSummary {
@After
maturityDate: MaturityDate
@After
orderDateTime : TransactionEventDateTime( @format = "yyyy-MM-dd HH:mm:ss.SSSSSSS")
}

will result in the following operations being generated:

import OrderWindowSummary
import MaturityDate
import TransactionEventDateTime
namespace vyne.casks {
@ServiceDiscoveryClient(serviceName = "cask")
service OrderWindowSummaryCaskService {
@HttpOperation(method = "GET" , url = "/api/cask/OrderWindowSummary/maturityDate/After/{after}")
operation findByMaturityDateAfter(
@PathVariable(name = "after") after : MaturityDate
) : OrderWindowSummary[]( MaturityDate > after )
@HttpOperation(method = "GET" , url = "/api/cask/OrderWindowSummary/orderDateTime/After/{after}")
operation findByOrderDateTimeAfter(
@PathVariable(name = "after") after : TransactionEventDateTime
) : OrderWindowSummary[]( TransactionEventDateTime > after )
}
}

@Between

Primary usage for this annotation is for Types with monotonically increasing values (e.g. dates).

In the below example resulting operation allows you to query by date ranges:

type alias MaturityDate as Date
type TransactionEventDateTime inherits Instant
type OrderWindowSummary {
@Between
maturityDate: MaturityDate
@Between
orderDateTime : TransactionEventDateTime( @format = "yyyy-MM-dd HH:mm:ss.SSSSSSS")
}

will result in the following operation being generated:

import OrderWindowSummary
import Symbol
import MaturityDate
import TransactionEventDateTime
namespace vyne.casks {
@ServiceDiscoveryClient(serviceName = "cask")
service OrderWindowSummaryCaskService {
@HttpOperation(method = "GET" , url = "/api/cask/OrderWindowSummary/maturityDate/Between/{start}/{end}")
operation findByMaturityDateBetween(
@PathVariable(name = "start") start : MaturityDate,
@PathVariable(name = "end") end : MaturityDate
) : OrderWindowSummary[]( MaturityDate >= start, MaturityDate < end )
@HttpOperation(method = "GET" , url = "/api/cask/OrderWindowSummary/orderDateTime/Between/{start}/{end}")
operation findByOrderDateTimeBetween(
@PathVariable(name = "start") start : TransactionEventDateTime,
@PathVariable(name = "end") end : TransactionEventDateTime
) : OrderWindowSummary[]( TransactionEventDateTime >= start, TransactionEventDateTime < end )
}
}

@Association (Deprecated)

We've deprecated this annotation, as we feel it's not very self-documenting. It will be replaced by new annotations - @FindOne and @FindMany in an upcoming release.

Adding @Association on top of field declaration:

type Symbol inherits String
type OrderWindowSummary {
@Association
symbol : Symbol
}

will generate the following operations:

import OrderWindowSummary
import Symbol
namespace vyne.casks {
@ServiceDiscoveryClient(serviceName = "cask")
service OrderWindowSummaryCaskService {
@HttpOperation(method = "GET" , url = "/api/cask/findOneBy/OrderWindowSummary/symbol/{Symbol}")
operation findOneBySymbol(
@PathVariable(name = "symbol") symbol : Symbol
) : OrderWindowSummary
@HttpOperation(method = "POST" , url = "/api/cask/findMultipleBy/OrderWindowSummary/symbol")
operation findMultipleBySymbol(
@RequestBody symbol : Symbol[]
) : OrderWindowSummary[]
}
}