Core & Client Communication Overview - struct-by-lightning/wpi-suite GitHub Wiki

See Networking with janeway for a more full description of the WPI Suite Network.

The Janeway client (which contains the client-side pieces of your modules) communicates with the core using HTTP. The core provides a RESTful API that clients can access. The basics of the WPISuite API are as follows:

Say there was a module called PostBoard, and it has a model class called PostBoardMessage. In order to save a PostBoardMessage in the core, a client would send a PUT HTTP request to the URL /API/postboard/postboardmessage with the body of the request containing the message to save in JSON form. To retrieve all of the messages that have been saved, the client would issue a GET request to the url /API/postboard/postboardmessage and they would get back a response whose body contains an array of PostBoardMessage in JSON form. To retrieve a specific message, a GET request can be made to /API/postboard/postboardmessage/id where id is an identifier of the particular message to retrieve.

The Janeway Network library makes it easy to send GET and PUT requests (along with most other types of HTTP request). To save a PostBoardMessage in the core you can use the Network library like this:

PostBoardMessage message; // the message to send

Request request = Network.getInstance().makeRequest("postboard/postboardmessage", HttpMethod.PUT);
request.setBody(message.toJSON());
request.addObserver(new AddMessageRequestObserver());
request.send();

The above snippet starts with a PostBoardMessage that should be sent. It then uses the Network library to generate a new request to the given URL using the given HTTP method. It then puts the message into the body of the request. Next, it adds an observer and sends the request. That's it! The request will automatically be sent using a different thread and your code beneath the send() call will continue to execute immediately.

One thing we didn't talk about is how to react to the response received from the core. That is was observers are for. Observers are of type RequestObserver and they contain a method called responseSuccess() that is called automatically when a successful response is received from the core. There are also responseError() and fail() methods that are called when the server returns an error, and when some other network error occurrs, respecively. If you do not need to react to the response to a request (which is unlikely) you do not need to add an observer to the request.

In order to enable the core to handle requests for a model, a module must provide an EntityManager for every model it intends to store in the core. An EntityManager handles all requests involving the model it is responsible for. If the PostBoardMessage EntityManager receives a PUT request with an attached message, it must save that message in the core database. It must also handle GET requests to retrieve messages.