SproutCore and ERRest

or Todos 06 - Building with ERRest

This tutorial is designed to supplement the "Todos" tutorial found on the SproutCore wiki.  In the Todos tutorial, chapter six contains many examples from other frameworks on how to set up a Rest server to use as the backend for SproutCore.  This tutorial will show you how to complete the tutorial using WebObjects and Project Wonder's ERRest framework.  Along the way we'll try to hit on a couple of other concepts that may augment your general WebObjects knowledge.

Project Creation

To get started create a new Wonder application and names it TodosRestServer.  In the proceeding steps please make the following choices:

1. For the package names you can specify something that makes sense for you.  In the example we use org.objectstyle.app and org.objectstyle.components.
2. During the add referenced projects phase be sure to add the ERRest and the JavaMemoryAdaptor frameworks.
   

For more information on creating a Wonder Application please visit wiki.wocommunity.org

Creating the Model

The Todos tutorial has one basic type of data that we need to model.  Please add a new model to the resources folder of your project.  Name the model "TodosModel" and then open the model in Eclipse's Entity Modeler Perspective.  Add an entity whose name and table name is "Task" and whose class name is org.objectstyle.model.Task.  Then add two attributes to the Task entity:

1. isDone of type Boolean
2. textDescription of type varchar255 

Since we are using the model in conjunction with a tutorial there is no need to really persist the data.  So we are going to use the JavaMemoryAdaptor framework to create the database.  Open the model's configuration and tell it to use EOMemoryPrototypes and set the adaptor to Memory.

Create the Migrations File

Right click the Task entity and choose the option "Generate Migration".  Copy the contents of the Modal Window.
Create a new package in your source folder and name it org.objectstyle.migrations.  After creating the package select it and paste the migration file into it.  Open the migration file (TodosModel0.java) and edit it to implement "IERXPostMigration" i.e. 

Then add the following method to the class.

Open your properties file and uncomment the following two lines:

Now every time you start the application you will get the default dataset recommended by the SproutCore tutorial.

For more information on working with Migrations please visit Project Wonder's JavaDoc

Starting the Server on a Specified Port

SproutCore has a proxy mechanism that maps a request to a domain name/ip address and port number.  By default when we debug our WebObjects applications in Eclipse it will choose a random port to run the application on.  This will become annoying because we will have to keep telling our SproutCore app the new port number every time we restart the application.  In addition you'll have to restart your SproutCore server for the change to take effect.   To avoid the hassle we are going to tell Eclipse which port number we want to run our application on.  Right click your application in eclipse's WO Explorer perspective and choose the "Properties" option.  Navigate to the section "Run/Debug Settings" select the application, choose edit, select the "WO" tab and then find the property "WOPort".  Change the property to use a port that makes sense for you.  In the example it is set to "55555"

Generating the Model Classes.

Open the EOGenerator file (TodosModel.eogen) that was created in the Resources folder along side your EOModel.  In the "Templates" section set the template folder to the location of your Wonder Entity Templates.  Then specify "_WonderEntity.java" and "WonderEntity.java" as the values for the "Template" and "Subclass Template" fields respectively.  Now Right Click the "TodosModel.eogen" file and choose "EOGenerate".

For more information about EOGenerator please visit: [EOGenerator on Object Style Wiki|] 

Updating Application.java

Open Application.java in Eclipse.  Update the Application's constructor to use DirectAction as the default request handler key and then add the ERXRouteRequestHandler for the Task entity i.e.

ERRest utilizes the concept of convention over configuration.  So when we tell the ERXRouteRequestHandler to addDefaultRoutes we are notifying that the request should use the convention defined methods to use in conjunction with the request's HTTP verb i.e. a GET request will map to indexAction and a POST request will map to createAction in the entity's rest controller that we are going to create in the next section. 

Creating the Task Entity's Rest Controller

Create a new package to place your controller in i.e. "org.objectstyle.controllers".  In that package create a new class named TaskController and have it extend ERXRouteController.  It is important to note that the name of the controller has to be the  entity's name + "Controller".

ERRest adds a lot of magic for you that makes setting up your request routes really easy.  For the tutorial we need to create a route that will fetch the stored tasks.  To accomplish this we first need to create the following methods:

When an HTTP GET comes into the server on the Task entity's route i.e. 

GET /cgi-bin/WebObjects/TodosRestServer.woa/ra/Task

the ERRest framework will know to look at indexAction for the response because that is the method defined by the convention.  In addition,  ERRest allows you to configure which attributes should be exposed for such requests.  Since we want to return all the entity's attributes, including the id, we need to specify that the queryFilter uses the method filterWithAllRecursive.  When we defined the Task entity in the model we called our text field "textDescription" instead of "description" to avoid overriding Enterprise Object's description method.  However, our SproutCore application expects an attribute named "description".  Fortunately, this is easy to fix.  In the showFilter method we add a filter that maps the attribute name to the format SproutCore anticipates.

Back in SproutCore

First we need to update the BuildFile file to include the proxy route to our Rest server i.e.

If you take a look closely at our route you might have noticed we have appended the route with ".sc".  ERRest has a concept called formatters that returns data in a format that the request expects i.e. xml, json, plist etc...  In fact, there is even a special formatter for SproutCore that uses the extension ".sc".  The SproutCore formatter includes a mapping that translates the "id" field to "guid" which is what SproutCore expects.

Now we need to add the route to our fetch function in data_sources/task.js.

One more important change we need to make is more of a gotcha.  In the Todos.TaskDataSource object we need to change the function didFetchTasks.  On the line:

change content to records.  So it looks like:

store.loadRecords(Todos.Task, response.get('body').records); 

The second gotcha.  ERRest has a bug where it returns attributes in underscore format instead of camel case (which SproutCore expects).  To fix this bug open the file ERXRestFormat.java and update the static variable SPROUTCORE to the following:

This bug has been submitted and may be fixed in the version of Wonder you are using.

Creating New Records

Please return to the Task entity's controller, TaskController.java.  Following the ERRest convention we now need to create a method to use in conjunction with the HTTP POST verb:

The one interesting part to note is in the fetch method (indexAction) we had a filter  (showFilter) that mapped "textDescription" to "description".  Because we now need to convert "description" to "textDescription" we need to create a filter that works in reverse i.e.

Now restart your application and then refresh your SproutCore application's browser.  You should now be able to use the "Add Task" button.  To test if your new tasks have been created just refresh the browser again.

That completes the WebObjects supplement to the Todos tutorial.

Going Beyond the Tutorial - Updating and Deleting Records

The first step in managing updates and deletes is to create the corresponding actions in our TaskController.java file.  Open TaskController.java in Eclipse and add the following methods.

When using the default routes the convention for updating and deleting records is to create methods named "updateAction" and "deleteAction" respectively.   Note, ERRest supports JSR 311 in the example we demonstrate this capacity by passing in a parameter to both methods that will automagically look up and find the proper object to update/delete based upon the information provided in the request.  This is basically a short hand way of writing the following method:

Changes back in SproutCore

The todos tutorial expects that the backend will always return an object to a PUT request.  However, ERRest always returns an array.  So, on the client we need to update our methods to include the function objectAt so that we get the object SproutCore anticipates.  For reference please see the completed Task Data Source File.