Defining the Service Contract

The first step when working with RPC is to define a contract in Quark. This contract defines the value classes, interfaces, and interaction patterns as well as how they can be used together.

Note: If you don’t want step-by-step guidance about how to create the contract and just want to start from a completed contract, there is a link to the full contract file at the bottom of this page.

Part 1: Creating the framework

This section helps you define the necessary structure for your service contract.

Relevant code:

@version("0.1.0")
package hello {

}

This creates a versioned Quark library in a package named hello.

Part 2: Adding value classes

This section defines the value classes needed by the Hello World RPC service. These classes hold the data that will be passed between the client and the server.

@version("0.1.0")
package hello {

   class Request {
      String text;
   }

   class Response {
      String result;
   }

}

Part 3: Interface

This section defines the interface needed by the Hello World RPC service. The interface contains the details of the interaction pattern being used, in this case a single request that generates a single response.

@version("0.1.0")
package hello {

   class Request {
      String text;
   }

   class Response {
      String result;
   }

   interface Hello extends Service {

      @delegate(self.rpc)
      Response hello(Request request);
   }

}

The Hello interface extends the Service interface supplied by Quark. This interface defines the actual communication mechanism between the client and the server.

The Hello interface specifies the use of the rpc interaction pattern by including @delegate(self.rpc). Note that this is a workaround; the preferred method for specifying the simple rpc interaction pattern is @delegate(rpc) but it is not currently working.

The Hello interface define a method named hello() that expects a request as an input parameter and returns a response object. This is the method that glues together the request and response; It is used in both the client and the server implementations. In the client it is used to send a request to the server and in the server it determines the proper response to that request.

Part 4: Client

This section defines the client processing code in Quark. This definition will be used within the client code in each supported target language to perform the actual communications work of the client.

Relevant code:

@version("0.1.0")
package hello {

   class Request {
      String text;
   }

   class Response {
      String result;
   }

   interface Hello extends Service {

      @delegate(self.rpc)
      Response hello(Request request);
   }

   class HelloClient extends Client, Hello {}
}

Define an empty class named HelloClient that extends the Quark Client integration type and uses the Hello interface we just defined. This class will be instantiated in the client code and used to send requests to the server. Most of the work of this class is abstracted away inside the Quark Client class.

Part 5: Server

This section defines the server in Quark. This definition will be used within the server written in each supported language to access the code within Quark and the installed integration that accepts the client request and packages up the response to send back to the client.

Relevant code:

@version("0.1.0")
package hello {

   class Request {
      String text;
   }

   class Response {
      String result;
   }

   interface Hello extends Service {

      @delegate(self.rpc)
      Response hello(Request request);
   }

   class HelloClient extends Client, Hello {}

   class HelloServer extends Server<Hello> {}
}

Define an empty class named HelloServer that extends the Quark Server implementation type. This type expects an implementation type, in this case the Hello interface defined above. This class will be instantiated in the server code and used to accept requests from the client and return responses to it based on those requests. Most of the work of this class is abstracted away inside the Quark Server class.

That’s it! The contract is fully defined now and ready to be turned into a library for your Hello clients and servers to use.