-
Notifications
You must be signed in to change notification settings - Fork 0
Application Design
The Android application is comprised mainly of two parts. The first part is the Single Cell Server code, which is responsible for communicating with the online Sage Cell Server and processing its responses in a way that can be used to display results properly in the Android application. The second part is Android-centric part, which contains activites and their fragments, as well as any GUI-related processing or code, along with some simple external libraries that allow for things like the Changelog and Terms of Service.
This package is responsible entirely for communicating with the server and parsing the responses. Every piece of communication is some subclass of Command.java (either CommandRequest.java or CommandReply.java depending on its type).
First, a unique SingleCellServer instance is created. Input is received from the Android SageActivity, which starts ServerTask. ServerTask starts by creating a new ExecuteRequest(), which is a subclass of CommandRequest. sendRequest() is called, which calls server.postEval(), taking the request's toJSON output as its argument. postEval sends at HTTP POST to the server, which responds with the WebSocket URLs. More can be read on initiating the session and parsing the message here and here. At this point, initializeSockets() is called, which initializes the iopub and shell sockets. The toString stringified request is then sent over the shell socket.
At this point, we listen on the iopub socket for incoming messages from the server. These messages are in JSON form, so in the onMessage() method of the iopub socket, we create new JSONObjects from each message, then pass the JSONObject to CommandReply.parse() to create a new CommandReply. CommandReply parses the message for any relevant information -- the type of calculation (if it is an Interact, for example), calculation outputs, images, files, and in the case of Interacts, controls. At this point, the addReply() method is called. Any relevant DataFiles are then downloaded, and specifically typed CommandOutput objects (Interacts, DisplayData, PyIn or PyOut, etc) are created for their relevant outputs. This triggers the onSageOutputListener and onSageAdditionalOutputListener, which passes the objects over to the Android-related code be displayed.
The rest of the application code deals with the GUI, fragments, activities, and any front-facing user interaction. The application is based mostly on management of Cell objects. Cell objects contain information relevant to the calculation that is then edited by and displayed to the user.
The main activity of the application is SageActivity. It displays a Cell, and allows a user to manipulate its contents, run a calculation, and view and manipulate the output. The view consists of a TextEdit field for input, a LinearLayout of buttons above it that allow for quick insertion of basic calculation structures, a Run button, and an OutputView (which is essentially a WebView that displays the outputs and allows for Interact interaction). Once the Run button is tapped, the input is passed to the Server, which runs through its processes as described above. Once the output is returned, OutputView handles each CommandOutput object, which are then used to create OutputBlock objects (which are essentially just formatted HTML)based on the type of output. These are then displayed in the OutputView. Interact sliders and/or selectors are created based on the types of controls defined in the Interact objects, and if manipulated, simply send updated JSON via the server (and update the cleared OutputBlocks accordingly). The Action Bar of SageActivity contains a New button, a Refresh button (which also indicates calculation progress while running, and if tapped, simply runs the calculation over again). In the overflow menu of the Action Bar, there are also links to the Sage website, the online tutorial, the reference manual, a Changelog popup, and a Share button. The Changelog popup calls on the Changelog library to display the latest changes, and the Share option creates a new Intent to share text with any application that will handle the link to the unique calculation.
Every calculation is stored as a CellData object. These objects are initially loaded from an cell_collection.xml file in /res/raw, but after this happens the first time, CellData objects are stored in a json file (which is done on onPause in SageActivity), which is then loaded up on the next start instead of the starting cell_collection.xml file. This allows for things like History and custom cells to exist. CellData all have a Group and other fields that describe their properties. The Group is important because that is how CellData Groups are defined and parsed by CellGroupsFragment (which allows the user to select a Group). These are essentially just ListAdapters and ListViews that parse Cells based on their Groups. Once a Group is selected, the Cells in that group are displayed in a CellListFragment. The CellListFragment is different from a typical ListView and Adapter because it inflates a unique layout which shows different Cell details and allows one to add/remove favorites. Cells also contain input and htmlData, which are restored upon loading SageActivity if they are History cells.
The Android code also relies on the Changelog class and the SimpleEula class. Changelog does as its name might suggest based on the changelog.txt file in /res/raw. SimpleEula allows the application to display the Sage Cell Server terms of service, which then allows the application to proceed and function correctly (the initial POST sends a ""accepted_tos", "true" set of parameters, or else the kernel is not created.).