Networking with janeway - struct-by-lightning/wpi-suite GitHub Wiki
Janeway communicates with the server by using the Network library, which consists of four key classes and one addressing system:
### The Network Class
The Network class is a singleton class designed to allow Janeway modules to easily create Requests using the default NetworkConfiguration, as well as access and change the default NetworkConfiguration. Network's makeRequest method will construct and return a Request which uses the default NetworkConfiguration. The getDefaultNetworkConfiguration method returns the default NetworkConfiguration. This allows you to get the configuration information necessary to construct your own Request.
###The NetworkConfiguration Class The NetworkConfiguration class stores information on how Requests should be made. Each instance of NetworkConfiguration stores the URL to the WPISuite API, a set of default request headers, and a set of RequestObservers. Request headers in a NetworkConfiguration, such as cookies, will be sent to the server by any Request using that NetworkConfiguration.
###HTTP Requests and Addressing in WPI Suite
WPI Suite uses HTTP requests and an addressing system to send those HTTP requests to the right places in the Core. The four HTTP requests used are; PUT, GET, DELETE, and POST for putting new Models, getting Models, deleting Models, and updating updating Models respectively. The address of each Entity Manager is a string of the form module/model, where module and model correspond to the Model you want and the module it is a part of. Each Entity Manager should only work with one type of Model. These addresses won't work unless you register your Entity Manager in the Manager Layer.
To differentiate between functions like getEntity and getAll in the Entity Manager, simply append /id to the address string, where id is the unique identifier of the object you want. The new form of the address will be module/model/id, where /id is optional. This extra component of the address will cause getEntity to be used instead of getAll because only one has an argument that needs to be passed in. This example shows how to put the address and the HTTP request into a Request. The table below shows the mapping between addresses, HTTP requests and Entity Manager methods as well as noting whether or not the Requests should have a body.
| HTTP | Args | Request Body | EntityManager | Usage |
|---|---|---|---|---|
| PUT | Model.toJSON() to be saved | makeEntity(...) | New Models | |
| GET | getAll(...) | Get all Models from database | ||
| GET | id | getEntity(id) | Get all Models with id | |
| POST | Model.toJSON() to be updated | update(...) | Update/Change existing Model | |
| DELETE | deleteAll(...) | Delete all Models | ||
| DELETE | id | deleteEntity(id) | Deletes first Model with given id |
See Advanced API for instructions on addressing and using the advanced functions in the Entity Managers.
### The Request Class The Request class is used for setting up and initiating a request to the server. By default, all Requests are made asynchronously. This means that Janeway will continue to operate and accept input from the user while the Request is made. A request will be sent to the server after the send method is called.
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.
### The RequestObserver Class
The RequestObserver class is used for taking action when a Request completes or fails. They can be added to a Request via the Request#addObserver(RequestObserver) method. 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. Finally, if the Request is unable to be sent to the server due to a timeout or some other error, the fail method of the requestObservers attached to the Request will be called. 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.