Platform API

Mercury has a small set of API for declaring microservices functions and sending events to functions.

Basic platform classes and utilities

  1. Platform - the platform class is a singleton object for managing life cycle of functions.

  2. PostOffice - a singleton object for sending events to functions.

  3. ServerPersonality - a singleton object for setting the personality or type of an application unit. e.g. REST, WEB, APP, RESOURCES and DEVOPS

  4. AppConfigReader - a singleton object for reading application.properties that can be overriden by run-time parameters or environment variables.

  5. CryptoApi - a convenient crypto library for common cryptographic tasks like hashing, AES and RSA encryption and digital signing.

  6. ManagedCache - a useful in-memory cache store.

  7. MultiLevelMap - a HashMap wrapper that allows you to retrieve item using the dot-bracket syntax. e.g. map.getElement(“hello.world[3]”)

  8. Utility - a convenient singleton object for commonly methods such as UTC time string, UTF, stream, file, etc.

  9. SimpleMapper - a preconfigured JSON serializer.

  10. SimpleXmlParser and SimpleXmlWriter - efficient XML serializer.

EventEnvelope

EventEnvelope is a vehicle for storing and transporting an event that contains headers and body. headers can be used to carry parameters and body is the message payload. Each event should have either or both of headers and body. You can set Java primitive, Map or PoJo into the body.

Mercury automatically performs serialization and deserialization using the EventEnvelope’s toBytes() and load(bytes) methods. For performance and network efficiency, it is using Gson and MsgPack for serialization into Map and byte array respectively.

EventEnvelope is used for both input and output. For simple use cases in asynchronous operation, you do not need to use the EventEnvelope. For RPC call, the response object is an EventEnvelope. The service response is usually stored in the “body” in the envelope. A service may also return key-values in the “headers” field.

Mercury is truly schemaless. It does not care if you are sending a Java primitive, Map or PoJo. The calling function and the called function must understand each other’s API interface contract to communicate properly.

Platform API

Obtain an instance of the platform object

Platform platform = Platform.getInstance();

Register a public function

To register a function, you can assign a route name to a function instance. You can also set the maximum number of concurrent workers in an application instance. This provides vertical scalability in addition to horizontal scaling by Docker/Kubernetes.

To create a singleton function, set instances to 1.

platform.register(String route, LambdaFunction lambda, int instances) throws IOException;

For example:

platform.register("hello.world", echo, 20);

Register a private function

Public functions are advertised to the whole system while private functions are encapsulated within an application instance.

You may define your function as private if it is used internally by other functions in the same application instance.

platform.registerPrivate(String route, LambdaFunction lambda, int instances) throws IOException;

Release a function

A function can be long term or transient. When a function is no longer required, you can cancel the function using the “release” method.

void release(String route) throws IOException;

Connect to the cloud

You can write truly event-driven microservices as a standalone application. However, it would be more interesting to connect the services together through a network event stream system.

To do this, you can ask the platform to connect to the cloud.

platform.connectToCloud();