Skip to Content

Wiki source code of Your First Rest Project

Version 39.1 by Pascal Robert on 2012/12/12 08:01
Hide last authors
Pascal Robert 28.1 1 {{toc}}{{/toc}}
Filippo Laurìa 21.1 2
Pascal Robert 5.1 3 = Introduction =
4
5 In the first part of the Blog tutorial, you will learn:
6
7 * How to create a EOModel for the database (we will use H2)
8 * How to use migrations to create the database tables
9 * How to use ERRest to create blog posts with JSON format and how to display the blog posts in HTML for readers
10
Pascal Robert 30.1 11 = Create a new project =
12
13 You will need to create a new project for this tutorial. In Eclipse, open the **File** menu, select **New** and select **Wonder REST Application**. Name your project as //BlogRest//.
14
Pascal Robert 5.1 15 = Create the database model =
16
Pascal Robert 30.1 17 == Database structure ==
18
Pascal Robert 5.1 19 We will build a small database model for the blog. The database will have two tables: BlogEntry and Author.
20
21 BlogEntry will have the following columns:
22
Pascal Robert 28.1 23 |= Column name |= Type |= Constraints
24 | id | integer | primary key
25 | title | string(255) |
26 | content | string(4000) |
27 | creationDate | timestamp |
Pascal Robert 38.1 28 | lastModified | timestamp |
Pascal Robert 28.1 29 | author | integer | relation with Author
Pascal Robert 5.1 30
31 Author will have the following columns:
32
Pascal Robert 28.1 33 |= Column name |= Type |= Constraints
34 | id | integer | primary key
Pascal Robert 30.1 35 | firstName | string(50) |
36 | lastName | string(50) |
37 | email | string(100) | unique
Pascal Robert 5.1 38
Pascal Robert 30.1 39 == Creating the EOModel ==
40
Pascal Robert 5.1 41 To create the database, we will first create a EOModel and use migrations to build the database on the file system (H2 will take care of creating the database file).
Pascal Robert 30.1 42
43 An EOModel consists of entities, attributes and relationships. When using it in a RDBMS context, an entity is a table (or a view), an attribute is a table column and a relationship is a join between two tables.
44
45 To create the EOModel, in the project right-click on the project name and select **New** > **EOModel**.
46
47 Name it **BlogModel** and in the plugin list, select **H2**. Click **Finish**.
48
49 The model should show up in a window that looks like this:
50
51 If it didn't show up, the window might have opened behind the main Eclipse window. If that's the case, open the **Window** menu and select the windows that have //Entity Modeler// in its name.
52
53 In the Entity Modeler window, click on **Default**, and for the **URL** field, type {{code}}jdbc:h2:~/BlogTutorial{{/code}}. When the database will be created, it will be stored in your home directory (/Users/youruser/ on OS X).
54
55 Now, right-click on **BlogModel** and select **New Entity**.
56
57 Type the following details in the **Basic** tab:
58
59 * **Name**: BlogEntry
60 * **Table Name**: BlogEntry
61 * **Class Name**: your.app.model.BlogEntry
62
63 Now, it's time to add the entity's attributes (aka, the table's columns). You will see that the entity already have an attributed named "id". That attribute is a integer for the primary key. Leave it there.
64
65 Let's create the first attribute: the title of the blog entry. Right-click on the entity and select **New Attribute**. Type the following values:
66
67 * **Name**: title
68 * **Column**: title
69 * **Prototype**: varchar255
70
71 When you use prototypes, you don't need to define the type (varchar, int, etc.) for the database, so by using prototypes, if you switch from a RDBMS system to another one, say from H2 to MySQL, you only need to change the JDBC connection string and bundle the EOF plugin for the RDBMS, no need to switch data types in the model.
72
73 Now, repeat the last two steps to create the other attributes for the **BlogEntry** entity, with the following values:
74
75 |= Attribute name |= Column |= Prototype
76 | content | content | longtext
77 | creationDate | creationDate | dateTime
Pascal Robert 38.1 78 | lastModified | lastModified | dateTime
Pascal Robert 30.1 79
80 If you did everything well, the list of attributes should look like this:
81
pauldlynch 36.1 82 You will notice that the attributes have a column with a lock in it. When a lock is present, it will use the value of that attribute for //UPDATE ... WHERE attribute = ''// statement. This is to do optimistic locking, aka to prevent data conflict when the data object was modified by two different users. Using timestamps for optimistic locking is not a good idea because for certain RDBMS, the value can be different because of milliseconds, so remove the locks on the **creationDate** attribute. The final list should look like this:
Pascal Robert 30.1 83
84 Next step is to create the **Author** entity. Create a new entity with **Author** at its name (and also as the table name), and for the class name, use **your.app.model.Author**. The attributes for this entity are:
85
86 |= Attribute name |= Column |= Prototype
87 | firstName | firstName | varchar50
88 | lastName | lastName | varchar50
89 | email | email | varchar100
90
91 Final list of attributes should look like this:
92
pauldlynch 36.1 93 Now, it's time to link the two entities together. An Author can have multiple blog entries, and a BlogEntry can only have one author. To create the relationship (the join), right-click on **Author** and select **New Relationship**. On your right, select **BlogEntry** in the list. On your left, select **to many BlogEntries**, and on your right, select **to one Author**. Now, in BlogEntry, we need to store the primary key of the author so that we can make the join. The relationship builder allow us to add that attribute, so make sure **and a new foreign key named** is checked (it is checked by default). The **Create Relationship** pane should look like this:
Pascal Robert 30.1 94
franc 34.1 95 If you check in the **Outline** tab, you should see that **Author** now have a **blogEntries** relationship, and **BlogEntry** have a **author** relationship.
Pascal Robert 30.1 96
franc 34.1 97 You are now ready to save the model. Save it (File > Save) and close the **Entity Modeler** window. If you open the **Sources** in the main Eclipse window, you will notice that the **Sources** folder contains a package named **your.app.model**.
Pascal Robert 30.1 98
franc 34.1 99 That package have four Java classes: **Author**, **Author**, **BlogEntry** and **BlogEntry**. Those classes were generated by Veogen, a templating engine build on Velocity. The two classes that starts with a underscore are recreated every time you change the EOModel, so if you want to change something in those classes, you need to change the template (no need for that right now). But you can change freely the two classes that don't have the underscore, and this is what we will be doing.
Pascal Robert 30.1 100
101 What we are going to do is to write a simple method that returns the full name of an author, e.g. a method that simply concatenate the first name, a space and the last name of the author. To do so, double-click on **Author.java** and add the following methods:
102
103 {{code}}
104
franc 34.1 105 public String fullName() {
Pascal Robert 30.1 106 return this.firstName() + " " + this.lastName();
107 }
108
109 {{/code}}
110
franc 34.1 111 Nothing fancy here. Now open **BlogEntry.java** and add the following method:
Pascal Robert 30.1 112
franc 34.1 113 {{code}}
114
115 @Override
116 public void awakeFromInsertion(EOEditingContext editingContext) {
117 super.awakeFromInsertion(editingContext);
118 this.setCreationDate(new NSTimestamp());
119 }
120
121 {{/code}}
122
123 Why are we adding this? **awakeFromInsertion** is a very good way of setting default values when creating a new instance of a Enterprise Object (EO). In this case, we want to set automatically the creation date without having the user to add that value.
124
125 Now, let's use migrations to actually create the database.
126
127 == Using migrations ==
128
pauldlynch 36.1 129 Migrations allow you to create the tables and columns (and some types of constraint). **Entity Modeler** has support to generate the code for the first migration, which is called "migration 0". To do that, open the EOModel (**BlogModel EOModel** in the **Resources** folder), right-click on the model name and select **Generate Migration**.
franc 34.1 130
131 Copy the generated code in the clipboard. Close **Entity Modeler** and in the main Eclipse window, right-click on **Sources**, select **New** and select **Class**.
132
133 Type **your.app.model.migrations** as the package and **BlogModel0** as the name of the class. Click **Finish**.
134
135 In the **Sources** folder, open the **your.app.model.migrations** package, a class named **BlogModel0** should be there. Delete everything in that file **EXCEPT** the first line (which should be //package your.app.model.migrations//) and paste the code that was generated by **Entity Modeler**. Save the file.
136
137 One last step: migrations are disabled by default. To enable them, you need to uncomment two properties in the **Properties** file that is located in the **Resources** folder. Open that file (double-click on it).
138
139 Remove the pound char in front of those two properties:
140
141 {{code}}
142
143 #er.migration.migrateAtStartup=true
144 #er.migration.createTablesIfNecessary=true
145
146 {{/code}}
147
148 After removing the pound char, the two properties should look like this:
149
150 {{code}}
151
152 er.migration.migrateAtStartup=true
153 er.migration.createTablesIfNecessary=true
154
155 {{/code}}
156
157 You are now ready to start the application so that it creates the database To do so, right-click on **Application.java** (in the **your.app** folder) and select **Run As** > **WOApplication**. In Eclipse's Console tab, you should see some output, including something similar to:
158
159 {{code}}
160
161 BlogRest[62990] INFO er.extensions.migration.ERXMigrator - Upgrading BlogModel to version 0 with migration 'your.app.model.migrations.BlogModel0@4743bf3d'
162 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing CREATE TABLE Author(email VARCHAR(100) NOT NULL, firstName VARCHAR(50) NOT NULL, id INTEGER NOT NULL, lastName VARCHAR(50) NOT NULL)
163 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE Author ADD PRIMARY KEY (id)
164 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing CREATE TABLE BlogEntry(authorID INTEGER NOT NULL, content TIMESTAMP NOT NULL, creationDate TIMESTAMP NOT NULL, id INTEGER NOT NULL, title VARCHAR(255) NOT NULL)
165 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE BlogEntry ADD PRIMARY KEY (id)
166 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE BlogEntry ADD CONSTRAINT "FOREIGN_KEY_BLOGENTRY_AUTHORID_AUTHOR_ID" FOREIGN KEY (authorID) REFERENCES Author (id)
167 BlogRest[62990] DEBUG NSLog - evaluateExpression: <er.h2.jdbcadaptor.ERH2PlugIn$H2Expression: "UPDATE _dbupdater SET version = ? WHERE modelname = ?" withBindings: 1:0(version), 2:"BlogModel"(modelName)>
168
169 {{/code}}
170
171 If you see this and that the application is running (it should open a window in your favorite browser), migration worked and your database have been created, congratulations You can now stop the application (click the square red button in Eclipse's Console tab) and continue to the next step.
172
Pascal Robert 30.1 173 = Creating REST controllers and routes =
franc 34.1 174
175 Project Wonder contains a framework called ERRest, which follow the same patterns as Ruby on Rails REST concepts. Using REST-style URLs is perfect for building a public blog and to create REST services to manage posting over HTTP with JSON, XML or other formats.
176
177 By default, a REST route in ERRest will generate a link like this:
178
179 {{code}}
180 /cgi-bin/WebObjects/AppName.woa/ra/EntityName/id
181 {{/code}}
182
183 So for our case, to get the first blog posting from BlogRest, the URL will look like this:
184
185 {{code}}
186 /cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries/1.html
187 {{/code}}
188
189 {{info}}
190 You can shorten the URL by using mod_rewrite in Apache httpd
191 {{/info}}
192
193 == Creating controllers ==
194
195 ERRest needs controllers to act as a broker between working with the objects and the routes. So let's create a controller for BlogEntry.
196
197 Create a Java class named **BlogEntryController**, in the **your.app.rest.controllers** package, that will extend from **er.rest.routes.ERXDefaultRouteController**. Click **Finish**.
198
199 When you extend from **ERXDefaultRouteController**, a bunch of methods are added to the subclass. Let's see what they are for.
200
201 * **updateAction**: to update a specific instance of BlogEntry
202 * **destroyAction**: to delete a specific instance of BlogEntry
203 * **showAction**: to get one specific instance of BlogEntry
204 * **createAction**: to create a new object (a new instance of BlogEntry)
205 * **indexAction**: to list all (or a sublist) of the objects.
206
207 {{info}}
208 In Project Wonder, *Action* at the end of a method is a convention for REST and Direct Actions, when you call those methods from certain components, you don't need to add the *Action* part.
209 {{/info}}
210
pauldlynch 36.1 211 For this tutorial, we will implement the **createAction** and **indexAction** methods. But first, we need to create a key filter. A key filter will... filter the input and the output of REST request so that you don't have to send all attributes for a blog entry. For example, we want to show the details for an author, but we don't want to show the password for the author (in real-life, the password would be encrypted)
franc 34.1 212
213 Add this method in **BlogEntryController**:
214
215 {{code}}
216
217 protected ERXKeyFilter filter() {
218 ERXKeyFilter personFilter = ERXKeyFilter.filterWithAttributes();
219 personFilter.setAnonymousUpdateEnabled(true);
220
221 ERXKeyFilter filter = ERXKeyFilter.filterWithAttributes();
222 filter.include(BlogEntry.AUTHOR, personFilter);
223 filter.setUnknownKeyIgnored(true);
224
225 return filter;
226 }
227
228 {{/code}}
229
pauldlynch 36.1 230 Now, let's implement the **createAction** method:
franc 34.1 231
232 {{code}}
233
234 public WOActionResults createAction() throws Throwable {
235 BlogEntry entry = create(filter());
236 editingContext().saveChanges();
237 return response(entry, filter());
238 }
239
240 {{/code}}
241
242 In 3 lines of code, you can create an object based on the request, save the new object to the database and return the new object in the response. Not bad, eh?
243
pauldlynch 36.1 244 Last step in the controller: implementing the **indexAction** method. Again, the code is simple:
franc 34.1 245
246 {{code}}
247
248 public WOActionResults indexAction() throws Throwable {
249 NSArray<BlogEntry> entries = BlogEntry.fetchAllBlogEntries(editingContext());
250 return response(entries, filter());
251 }
252
253 {{/code}}
254
255 That code simply fetch all blog entries and return them in the response.
256
257 We can now go to the next step: adding the routes.
258
259 == Adding the routes ==
260
261 A route in ERRest is simply a way to define the URL for the entities and to specify which controller the route should use. When your controller extends from **ERXDefaultRouteController**, it's easy to register a controller and a route. In **Application.java**, in the **Application** constructor, add the following code:
262
263 {{code}}
264
265 ERXRouteRequestHandler restRequestHandler = new ERXRouteRequestHandler();
266 restRequestHandler.addDefaultRoutes(BlogEntry.ENTITY_NAME);
267 ERXRouteRequestHandler.register(restRequestHandler);
268 setDefaultRequestHandler(restRequestHandler);
269
270 {{/code}}
271
272 The **addDefaultRoutes** method do all of the required magic, and use convention. That's why we had to name the controller **BlogEntryController**, because the convention is <EntityName>Controller.
273
274 We are now reading to add and list blog postings Start the application and take notice of the URL. It should be something like //[[http:~~/~~/yourip:someport/cgi-bin/WebObjects/BlogRest.woa>>http://yourip:someport/cgi-bin/WebObjects/BlogRest.woa_]]//
275
276 == Adding posts and authors with curl ==
277
278 Since we didn't implement any HTML for our REST routes, we will create blog entries with //curl//, an open source HTTP client that is bundled with Mac OS X (you can use another client, like wget, if you like too). So let's create a blog entry.
279
280 To create a blog entry, you need to use the POST HTTP method. We will use JSON as the format since it's a bit less chatty than XML. So if the URL to the application is //[[http:~~/~~/192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa>>http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa_]], the full curl// command will be:
281
282 {{code}}
283 curl -X POST -v -d '{ "title": "First post", "content": "Some text", "author": { "firstName": "Pascal", "lastName": "Robert", "email": "probert@macti.ca" } }' http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.json
284 {{/code}}
285
286 The response should look this:
287
288 {{code}}
289
290 HTTP/1.0 201 Apple WebObjects
291 Content-Length: 249
292 x-webobjects-loadaverage: 0
293 Content-Type: application/json
294
295 {"id":1,"type":"BlogEntry","content":"Some text","creationDate":"2011-12-27T21:59:08Z","title":"First post","author":{"id":1,"type":"Author","email":"probert@macti.ca","firstName":"Pascal","lastName":"Robert"}}
296
297 {{/code}}
298
299 To get a list of blog entries:
300
301 {{code}}
302
303 curl -X GET http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.json
304
305 {{/code}}
306
307 You can stop the application and proceed to the next step.
308
309 == Adding HTML views for blog posts ==
310
311 Now, let's build a HTML view for blog posts (you don't want your readers to get your posts by JSON, right?). Again, we will use convention to make it work easily. Open up **BlogEntryController** and add the following method:
312
313 {{code}}
314
315 @Override
316 protected boolean isAutomaticHtmlRoutingEnabled() {
317 return true;
318 }
319
320 {{/code}}
321
322 Switching the return value of this method says that we will follow a certain convention for HTML components. The convention for automatic HTML routing is that the component should be named <EntityName><Action>Page.wo. So in our case, the component will be **BlogEntryIndexPage**. Right-click on the project name in Eclipse and select **New** > **WOComponent**. Change the name to **BlogEntryIndexPage** and check the **Create HTML contents** button. Click **Finish**.
323
pauldlynch 36.1 324 The next step to get it to work is to make **BlogEntryIndexPage** to implement the **er.rest.routes.IERXRouteComponent** interface.
franc 34.1 325
326 {{code}}
327
328 import er.rest.routes.IERXRouteComponent;
329
330 public class BlogEntryIndexPage extends WOComponent implements IERXRouteComponent {
331
332 {{/code}}
333
334 So now, the automatic HTML routing will send the request for **ra/blogEntries.html** to the **BlogEntryIndexPage** component. But we don't have any content in this component, so let's make a method to fetch all blog entries per creation date in descending order. So in **BlogEntryIndexPage.java**, add the following method:
335
336 {{code}}
337
338 public NSArray<BlogEntry> entries() {
339 EOEditingContext ec = ERXEC.newEditingContext();
340 return BlogEntry.fetchAllBlogEntries(ec, BlogEntry.CREATION_DATE.descs());
341 }
342
343 {{/code}}
344
345 We need to use that method in a WORepetition, and for that loop, we need a BlogEntry variable to iterate in the list, so add the following code to **BlogEntryIndexPage.java**:
346
347 {{code}}
348
349 private BlogEntry entryItem;
350
351 public BlogEntry entryItem() {
352 return entryItem;
353 }
354
355 public void setEntryItem(BlogEntry entryItem) {
356 this.entryItem = entryItem;
357 }
358
359 {{/code}}
360
361 The Java part is done, so let's add the loop inside the component. Open **BlogEntryIndexPage.wo** (it's located in the **Component** folder) and right after the <body> tag, add:
362
363 {{code}}
364
365 <wo:loop list="$entries" item="$entryItem">
366 <p><wo:str value="$entryItem.title" /></p>
367 <p><wo:str value="$entryItem.author.fullName" /></p>
368 </wo:loop>
369
370 {{/code}}
371
372 That component code will loop over the blog entries and display the title of the entry + the name of the author. Save everything and run the application.
373
374 If you go to [[http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.html]], you will see the list of blog entries
375
376 Now that we have a list of blog entries, let's make a page to show the content of a blog entry. Create a new component named **BlogEntryShowPage**.
377
pauldlynch 36.1 378 Open **BlogEntryShowPage.java** and make sure the class implements&nbsp;**er.rest.routes.IERXRouteComponent**.
franc 34.1 379
380 {{code}}
381
382 import er.rest.routes.IERXRouteComponent;
383
384 public class BlogEntryShowPage extends WOComponent implements IERXRouteComponent {
385
386 {{/code}}
387
388 We need to add other methods to receive the BlogEntry object from the controller. In **BlogEntryShowPage.java**, add:
389
390 {{code}}
391
392 private BlogEntry blogEntry;
393
394 @ERXRouteParameter
395 public void setBlogEntry(BlogEntry blogEntryFromController) {
396 this.blogEntry = blogEntryFromController;
397 }
398
399 public BlogEntry blogEntry() {
400 return this.blogEntry;
401 }
402
403 {{/code}}
404
405 The **@ERXRouteParameter** annotation tells the REST framework that it can automatically receive an object from the controller. And again, it's convention at work. You have to use the annotation and the setter name should be //set<EntityName>//, so for a BlogEntry, it's //setBlogEntry//, for a Author, it will be //setAuthor//.
406
407 The Java part of the work is done, so save the Java class. It's time to work on the component part. Open **BlogEntryShowPage.wo** and between the <body></body> part, add:
408
409 {{code}}
410
411 <h1><wo:str value="$blogEntry.title" /></h1>
412 <p><wo:str value="$blogEntry.content" /></p>
413 <p>Created on: <wo:str value="$blogEntry.creationDate" dateformat="%Y/%m/%d" /></p>
414 <p>Added by: <wo:str value="$blogEntry.author.fullName" /></p>
415
416 {{/code}}
417
418 Our view component is done, the only thing remaining is a link for the blog entry list (BlogEntryIndexPage) to the view page (BlogEntryShowPage). Save **BlogEntryShowPage.wo** and open **BlogEntryIndexPage.wo**. We are going to add a link on the title, you will replace to replace this:
419
420 {{code}}
421
422 <p><wo:str value="$entryItem.title" /></p>
423
424 {{/code}}
425
426 with:
427
428 {{code}}
429
430 <p><wo:ERXRouteLink entityName="BlogEntry" record="$entryItem" action="show"><wo:str value="$entryItem.title" /></wo:ERXRouteLink></p>
431
432 {{/code}}
433
434 Save the component and run the app. Go to [[http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.html]] to get the list of posts, and you should see a link on the title. Click on it, and now you get the full details of the blog entry
435
Pascal Robert 38.1 436 The REST part of this tutorial is now complete, [[you can now move to the next part of the tutorial>>Your First Framework]].