A CRUD address service with a mutex-locked repository
The complete source of webServices_addresses.ek9, compiled by the EK9 compiler. Shown on webServices.html.
#!ek9 defines module site.webServices.addresses defines type //Just for strong typing - no constraints AddressId as String defines record Address id <- AddressId() street <- String() street2 <- String() city <- String() state <- String() zipcode <- String() Address() -> id as AddressId street as String street2 as String city as String state as String zipcode as String this.id :=: id this.street :=: street this.street2 :=: street2 this.city :=: city this.state :=: state this.zipcode :=: zipcode Address() -> from as Address this :=: from Address() -> from as Optional of Address if from? this :=: from.get() //Copy operator :=: -> from as Address id :=: from.id street :=: from.street street2 :=: from.street2 city :=: from.city state :=: from.state zipcode :=: from.zipcode //Merge only if incoming address parts are set operator :~: -> address as Address if address.street? street :=: address.street if address.street2? street2 :=: address.street2 if address.city? city :=: address.city if address.state? state :=: address.state if address.zipcode? zipcode :=: address.zipcode override operator ? as pure //street2 is optional and can be omitted <- rtn as Boolean: id? and street? and city? and state? and zipcode? defines text for "en" AddressToOutputFormat toJSON() -> address as Address `{ "address": { "id": "${address.id}", "street": "${address.street}",${optionalJSON("street2", address.street2)} "city": "${address.city}", "state": "${address.state}", "zipcode": "${address.zipcode}" } }` defines function //Used for specific operations to be applied to a set of addresses addressOperation() as abstract -> addresses as AddressAccess address as Address //deals with wrapping the operation in the calls to deal with mutex lock. safeOperation() -> lockedAddressSet as MutexLock of AddressSet address as Address operation as addressOperation accessKey <- (address, operation) extends MutexKey of AddressSet as function operation(lockedItem, address) require lockedAddressSet.enter(accessKey) //The built-in JSON type reads the text; a part that is not there stays unset. addressFromJson() -> addressInJSONFormat as String <- rtn as Address: Address() parsed <- JSON().parse(addressInJSONFormat) if parsed.isOk() address <- parsed.ok().get("address") rtn.id: AddressId(textOf(address, "id")) rtn.street: textOf(address, "street") rtn.street2: textOf(address, "street2") rtn.city: textOf(address, "city") rtn.state: textOf(address, "state") rtn.zipcode: textOf(address, "zipcode") //The text a JSON property holds (not its JSON form, which is quoted). textOf() -> json as JSON property as String <- rtn as String: cat [json.get(property)] | collect as String copyAddress() -> from as Address <- to as Address: Address(from) wrapInBrackets() -> mainValue as String <- rtn as String: `[ ${mainValue} ]` commaSeparated() -> firstPart String secondPart String <- rtn as String: firstPart? and secondPart? <- `${firstPart},${secondPart}` : String() addressToJSON() -> address as Address <- addressAsString as String: AddressToOutputFormat("en").toJSON(address) addressListToJSON() -> addresses as List of Address <- listAsString as String: cat addresses | map with addressToJSON | join with commaSeparated | map with wrapInBrackets | collect as String //An unset value must not end up in the text: interpolating it would leave the whole text unset. optionalJSON() as pure -> name as String mainValue as String <- rtn as String: mainValue? <- ` "${name}": "${mainValue}",` else "" defines trait AddressAccess hash() <- rtn as String: String() hashOfAddress() -> id as AddressId <- rtn as String? require id? rtn: String() byId() -> id as AddressId <- rtn as Address? listAll() <- rtn as List of Address: List() of Address operator += -> address as Address require address? operator -= -> address as Address require address? //merge with an existing address operator :~: -> address as Address require address? //replace an existing address operator :^: -> address as Address require address? operator contains as pure -> addressId as AddressId <- rtn as Boolean: Boolean() defines class AddressSet with trait of AddressAccess //The etag of the whole set: the hash of every address's own hash, so the same addresses give the same etag. hash as String: String() addresses <- Dict() of (AddressId, Address) hashes <- Dict() of (AddressId, String) override hash() <- rtn as String: this.hash //Unset for an address that is not held. override hashOfAddress() -> id as AddressId <- rtn as String: hashes.getOrDefault(id, String()) override byId() -> id as AddressId <- rtn as Address: Address(addresses.getOrDefault(id, Address())) override listAll() <- rtn <- List() of Address iter <- addresses.values() cat iter | map with copyAddress > rtn private includeAddress() -> address as Address copy <- Address(address) addresses += DictEntry(copy.id, copy) hashes += DictEntry(copy.id, Digest().SHA256(addressToJSON(copy))) updateHash() private updateHash() allHashes <- cat hashes.values() | collect as String hash :=: Digest().SHA256(allHashes) override operator += -> address as Address require address? if this not contains address includeAddress(address) override operator -= -> address as Address require address.id? addresses -= address.id hashes -= address.id updateHash() override operator :~: -> address as Address require address.id? //We don't assert whole address because it can be partial currentAddress <- addresses.getOrDefault(address.id, Address()) if currentAddress? //make a new copy and then merge the two. updatedAddress <- Address(currentAddress) updatedAddress :~: address includeAddress(updatedAddress) override operator :^: -> address as Address require address? if this contains address includeAddress(address) operator contains as pure -> address as Address <- rtn as Boolean: this contains address.id override operator contains as pure -> addressId as AddressId <- rtn as Boolean: addresses contains addressId default operator ? //Example of wrapping shared data set in a mutex lock. LockableAddressSet with trait of AddressAccess lockedAddressSet as MutexLock of AddressSet: MutexLock(AddressSet()) override hash() <- rtn as String: String() accessKey <- (rtn) is MutexKey of AddressSet as function rtn :=: lockedItem.hash() require lockedAddressSet.enter(accessKey) override hashOfAddress() -> id as AddressId <- rtn as String: String() accessKey <- (id, rtn) is MutexKey of AddressSet as function rtn :=: lockedItem.hashOfAddress(id) require lockedAddressSet.enter(accessKey) override byId() -> id as AddressId <- rtn as Address: Address() accessKey <- (id, rtn) is MutexKey of AddressSet as function rtn :=: lockedItem.byId(id) require lockedAddressSet.enter(accessKey) override listAll() <- rtn <- List() of Address accessKey <- (rtn) is MutexKey of AddressSet as function rtn += lockedItem.listAll() require lockedAddressSet.enter(accessKey) override operator += -> address as Address //You can inline this simple dynamic function if you wish //Also used named parameters safeOperation( lockedAddressSet: lockedAddressSet, address: address, operation: () is addressOperation (addresses += address) ) override operator -= -> address as Address //Or you can inline all on one line. safeOperation(lockedAddressSet, address, () is addressOperation (addresses -= address)) override operator :~: -> address as Address //Or define a dynamic function and pass in as delegate (my preferred way) operation <- () is addressOperation addresses :~: address safeOperation(lockedAddressSet, address, operation) override operator :^: -> address as Address operation <- () is addressOperation addresses :^: address safeOperation(lockedAddressSet, address, operation) override operator contains as pure -> addressId as AddressId <- rtn as Boolean: false accessKey <- (addressId, rtn) is MutexKey of AddressSet as function rtn :=: lockedItem contains addressId require lockedAddressSet.enter(accessKey) default operator ? defines function plainNonCacheableHTTPResponse() <- rtn as HTTPResponse: () with trait of HTTPResponse override cacheControl() as pure <- rtn as String: "no-store,max-age=0" override contentType() as pure <- rtn as String: "text/plain" override contentLanguage() as pure <- rtn as String: "en" default operator ? cacheableHTTPResponse() <- rtn as HTTPResponse: () with trait of HTTPResponse override cacheControl() as pure <- rtn as String: "public,max-age=5,must-revalidate" override contentType() as pure <- rtn as String: "application/json" override contentLanguage() as pure <- rtn as String: "en" default operator ? //The answer to a change: a status (and a body or location if there is one) decided before it is made. //Named parameters in the dynamic variable capture, and 'by' to delegate the rest of the trait. outcomeHTTPResponse() -> status as Integer detail as String location as String <- response as HTTPResponse: ( status: status, detail: detail, location: location, nonCacheable: plainNonCacheableHTTPResponse() ) with trait of HTTPResponse by nonCacheable override status() as pure <- rtn as Integer: status override content() <- rtn as Bytes: detail? <- Bytes().withUtf8(detail) else Bytes() override contentLocation() as pure <- rtn as String: location default operator ? defines class ByETagHTTPResponse with trait of HTTPResponse by delegate delegate as HTTPResponse? addressId as AddressId? provideContentLocation as Boolean? status <- Integer() etagOfAddress <- String() default private ByETagHTTPResponse() //The etag is the hash of the address: when there is none, the address is not there. ByETagHTTPResponse() -> addressId as AddressId etagOfAddress as String delegate as HTTPResponse provideContentLocation as Boolean require addressId? and delegate? and provideContentLocation? this.addressId: addressId this.provideContentLocation: provideContentLocation this.delegate: delegate this.etagOfAddress :=: etagOfAddress if etagOfAddress? status :=: 200 else status :=: 404 ByETagHTTPResponse() -> addressId as AddressId etagOfAddress as String delegate as HTTPResponse this( addressId: addressId, etagOfAddress: etagOfAddress, delegate: delegate, provideContentLocation: true ) override etag() <- rtn as String: etagOfAddress override status() as pure <- rtn as Integer: status override contentLocation() as pure <- rtn as String: String() httpBadRequest <- 400 rtn: status < httpBadRequest and provideContentLocation <- `/addresses/${addressId}` else String() default operator ? <?- REST web service. Each method does its work first, then answers with a response that already knows its status: the server asks a response for its headers and status before it asks for its content. -?> defines service //The Name of the and the uri it is mapped to Addresses for :/addresses open //It is still possible to use dynamic variable capture, like this. byId() as GET for :/{address-id} -> id as String :=: PATH "address-id" //required because different name <- response as HTTPResponse? repository as Repository! addressId <- AddressId(id) address <- repository.addresses().byId(addressId) delegate <- ByETagHTTPResponse(addressId, repository.addresses().hashOfAddress(addressId), cacheableHTTPResponse()) response: (address, delegate) with trait of HTTPResponse by delegate override content() <- rtn as Bytes: address? <- Bytes().withUtf8(addressToJSON(address)) else Bytes() default operator ? //A POST operator += for :/ -> request as HTTPRequest :=: REQUEST <- response as HTTPResponse? repository as Repository! address <- addressFromJson(request.content().toText("utf-8")) status <- 201 detail <- String() location <- String() //But the server sets the ID! if address.id? status := 422 //unprocessable entity detail: "Do not supply ID in Address, server will set this" else address.id: AddressId(GUID()) if not address? status := 422 //unprocessable entity detail: "An address needs a street, city, state and zipcode" else if repository.addresses() contains address.id status := 409 //conflict else repository.addresses() += address location: `/addresses/${address.id}` response: outcomeHTTPResponse(status, detail, location) //A DELETE operator -= for :/{id} -> id as String //Assume PATH <- response as HTTPResponse? repository as Repository! addressId <- AddressId(id) status <- 404 //not found //Only if the address is there can we delete it! if repository.addresses() contains addressId repository.addresses() -= repository.addresses().byId(addressId) status := 204 //no content response: outcomeHTTPResponse(status, String(), String()) //A PATCH which is a merge operator :~: for :/{id} -> id as String //Assume PATH incomingContent as String :=: CONTENT <- response as HTTPResponse? repository as Repository! addressId <- AddressId(id) address <- addressFromJson(incomingContent) status <- 204 //no content if repository.addresses() not contains addressId status := 404 //not found else if not address.id? status := 422 //unprocessable entity else if address.id <> addressId status := 400 //the id on the url is not the same as the id in the body content else repository.addresses() :~: address response: outcomeHTTPResponse(status, String(), String()) //A PUT which is a replace for an existing address operator :^: for :/{id} -> id as String //Assume PATH content as String :=: CONTENT <- response as HTTPResponse? repository as Repository! addressId <- AddressId(id) address <- addressFromJson(content) status <- 204 //no content if repository.addresses() not contains addressId status := 404 //not found else if not address? status := 422 //unprocessable entity else if address.id <> addressId status := 400 //the id on the url is not the same as the id in the body content else repository.addresses() :^: address response: outcomeHTTPResponse(status, String(), String()) //Note it is now possible to use named parameters in dynamic variable capture //So now, we can do a simpler one liner, define the name of the property and use an expression //to set it up, then use the 'by' on a trait to delegate as much or as little as we want to it. listAll() for :/ <- response as HTTPResponse: ( cacheable: cacheableHTTPResponse() ) with trait of HTTPResponse by cacheable repository as Repository! override etag() <- rtn as String: repository.addresses().hash() override status() as pure <- rtn as Integer: 200 override content() <- rtn as Bytes: Bytes().withUtf8(addressListToJSON(repository.addresses().listAll())) default operator ? defines component Repository as abstract addresses() as pure abstract <- rtn as AddressAccess? default operator ? InMemoryRepository extends Repository addresses as AddressAccess: LockableAddressSet() InMemoryRepository() addresses += Address(id: AddressId("a1"), street: "121 Admin Rd.", street2: String(), city: "Concord", state: "NH", zipcode: "03301") addresses += Address(id: AddressId("a2"), street: "67 Paperwork Ave", street2: String(), city: "Manchester", state: "NH", zipcode: "03101") addresses += Address(id: AddressId("a3"), street: "15 Rose St", street2: "Apt. B-1", city: "Concord", state: "NH", zipcode: "03301") addresses += Address(id: AddressId("a4"), street: "39 Sole St.", street2: String(), city: "Concord", state: "NH", zipcode: "03301") addresses += Address(id: AddressId("a5"), street: "99 Mountain Rd.", street2: String(), city: "Concord", state: "NH", zipcode: "03301") override addresses() as pure <- rtn as AddressAccess: addresses default operator ? defines application //SERVING wiring: this application registers the REST service, so any program using //it MUST create an HTTP instance. EK9 enforces that both ways — a program wiring this //application without HTTP is E12020 (the service could never receive a request), and //an HTTP program wired to an application with no services is E12021. AccessPoint register InMemoryRepository() as Repository register Addresses() //COMPONENT wiring only: no service is registered here, so a plain (non-serving) //program can use it. Splitting the two is the point — conflating them is what //leaves a REST service registered and permanently unreachable. RepositoryOnly register InMemoryRepository() as Repository defines program //Serves the Addresses service on the port given, until the process is stopped. ServeAddresses() with application of AccessPoint -> port as Integer try -> server <- HTTP(NetworkProperties(port: port, localOnly: true)) server.serve() //Uses the component-only application: it exercises the repository and exits, so it //must NOT be wired to the service-registering AccessPoint. TestAddressOutput with application of RepositoryOnly //Expect injection repository as Repository! stdout <- Stdout() address1 <- Address(id: AddressId("t1"), street: "121 Admin Rd.", street2: String(), city: "Concord", state: "NH", zipcode: "03301") address2 <- Address(id: AddressId("t2"), street: "15 Rose St", street2: "Apt. B-1", city: "Concord", state: "NH", zipcode: "03301") addresses <- [address1, address2] iter <- addresses.iterator() //convert contents in iterator to a list theAddresses <- cat iter | collect as List of Address require theAddresses? stdout.println("Address as JSON") stdout.println(addressToJSON(address1)) jsonAddress <- addressFromJson(addressToJSON(address2)) stdout.println(`Rebuilt address is [${addressToJSON(jsonAddress)}]`) stdout.println("Now arrays") stdout.println(addressListToJSON(addresses)) stdout.println("Done basics now all addresses") allAddresses <- repository.addresses().listAll() stdout.println(`Hash of all addresses is [${repository.addresses().hash()}]`) stdout.println(addressListToJSON(allAddresses)) stdout.println("Done!")
Download webServices_addresses.ek9
Output
TestAddressOutput
Address as JSON
{
"address":
{
"id": "t1",
"street": "121 Admin Rd.",
"city": "Concord",
"state": "NH",
"zipcode": "03301"
}
}
Rebuilt address is [{
"address":
{
"id": "t2",
"street": "15 Rose St", "street2": "Apt. B-1",
"city": "Concord",
"state": "NH",
"zipcode": "03301"
}
}]
Now arrays
[ {
"address":
{
"id": "t1",
"street": "121 Admin Rd.",
"city": "Concord",
"state": "NH",
"zipcode": "03301"
}
},{
"address":
{
"id": "t2",
"street": "15 Rose St", "street2": "Apt. B-1",
"city": "Concord",
"state": "NH",
"zipcode": "03301"
}
} ]
Done basics now all addresses
Hash of all addresses is [386368B779B099210EB8DA9D15158EC4D4D412655294648E9BFBD6DE78F30875]
[ {
"address":
{
"id": "a1",
"street": "121 Admin Rd.",
"city": "Concord",
"state": "NH",
"zipcode": "03301"
}
},{
"address":
{
"id": "a2",
"street": "67 Paperwork Ave",
"city": "Manchester",
"state": "NH",
"zipcode": "03101"
}
},{
"address":
{
"id": "a3",
"street": "15 Rose St", "street2": "Apt. B-1",
"city": "Concord",
"state": "NH",
"zipcode": "03301"
}
},{
"address":
{
"id": "a4",
"street": "39 Sole St.",
"city": "Concord",
"state": "NH",
"zipcode": "03301"
}
},{
"address":
{
"id": "a5",
"street": "99 Mountain Rd.",
"city": "Concord",
"state": "NH",
"zipcode": "03301"
}
} ]
Done!