Skip to Content

Wiki source code of Your First Rest Project

Last modified by Steve Peery on 2013/09/06 11:02
Show last authors
1 {{toc/}}
2
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
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** (or **ERRest Application**, according to //your// WOLips version). Name your project as //BlogRest//.
14
15 = Create the database model =
16
17 == Database structure ==
18
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
23 |=(((
24 Column name
25 )))|=(((
26 Type
27 )))|=(((
28 Constraints
29 )))
30 |(((
31 id
32 )))|(((
33 integer
34 )))|(((
35 primary key
36 )))
37 |(((
38 title
39 )))|(((
40 string(255)
41 )))|(((
42
43 )))
44 |(((
45 content
46 )))|(((
47 string(4000)
48 )))|(((
49
50 )))
51 |(((
52 creationDate
53 )))|(((
54 timestamp
55 )))|(((
56
57 )))
58 |(((
59 lastModified
60 )))|(((
61 timestamp
62 )))|(((
63
64 )))
65 |(((
66 author
67 )))|(((
68 integer
69 )))|(((
70 relation with Author
71 )))
72
73 Author will have the following columns:
74
75 |=(((
76 Column name
77 )))|=(((
78 Type
79 )))|=(((
80 Constraints
81 )))
82 |(((
83 id
84 )))|(((
85 integer
86 )))|(((
87 primary key
88 )))
89 |(((
90 firstName
91 )))|(((
92 string(50)
93 )))|(((
94
95 )))
96 |(((
97 lastName
98 )))|(((
99 string(50)
100 )))|(((
101
102 )))
103 |(((
104 email
105 )))|(((
106 string(100)
107 )))|(((
108 unique
109 )))
110
111 == Creating the EOModel ==
112
113 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).
114
115 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.
116
117 To create the EOModel, in the project right-click on the project name and select **New** -> **EOModel**.
118
119 Name it **BlogModel** and in the plugin list, select **H2**. Click **Finish**.
120
121 The model should show up in a window that looks like this:
122
123 [[image:attach:EOModeler.png]]
124
125 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.
126
127 In the Entity Modeler window, click on **Default**, and for the **URL** field, type
128
129 {{code}}
130 jdbc:h2:~/BlogTutorial
131 {{/code}}
132
133 . When the database will be created, it will be stored in your home directory (/Users/youruser/ on OS X).
134
135 You can also specify an absolute path where to store in you h2 database files. For example on Windows OS **URL** field can be like this:
136
137 {{code}}
138 jdbc:h2:C:/Users/ ... /BlogTutorial
139 {{/code}}
140
141 //Notice, in the path, *nix like file separator "/" instead of Windows like// "\" (as you can read [[here>>url:http://www.h2database.com/html/faq.html||shape="rect"]]).
142
143
144
145 Now, right-click on **BlogModel** and select **New Entity**.
146
147 Type the following details in the **Basic** tab:
148
149 * **Name**: BlogEntry
150 * **Table Name**: BlogEntry
151 * **Class Name**: your.app.model.BlogEntry
152
153 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.
154
155 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:
156
157 * **Name**: title
158 * **Column**: title
159 * **Prototype**: varchar255
160
161 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.
162
163 Now, repeat the last two steps to create the other attributes for the **BlogEntry** entity, with the following values:
164
165 |=(((
166 Attribute name
167 )))|=(((
168 Column
169 )))|=(((
170 Prototype
171 )))
172 |(((
173 content
174 )))|(((
175 content
176 )))|(((
177 longtext
178 )))
179 |(((
180 creationDate
181 )))|(((
182 creationDate
183 )))|(((
184 dateTime
185 )))
186 |(((
187 lastModified
188 )))|(((
189 lastModified
190 )))|(((
191 dateTime
192 )))
193
194 If you did everything well, the list of attributes should look like this:
195
196 [[image:attach:list_wlock.png]]
197
198 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:
199
200 [[image:attach:list.png]]
201
202 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:
203
204 |=(((
205 Attribute name
206 )))|=(((
207 Column
208 )))|=(((
209 Prototype
210 )))
211 |(((
212 firstName
213 )))|(((
214 firstName
215 )))|(((
216 varchar50
217 )))
218 |(((
219 lastName
220 )))|(((
221 lastName
222 )))|(((
223 varchar50
224 )))
225 |(((
226 email
227 )))|(((
228 email
229 )))|(((
230 varchar100
231 )))
232
233 Final list of attributes should look like this:
234
235 [[image:attach:author_list.png]]
236
237 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:
238
239 [[image:attach:relationship.png]]
240
241 If you check in the **Outline** tab, you should see that **Author** now have a **blogEntries** relationship, and **BlogEntry** have a **author** relationship.
242
243 [[image:attach:outline_tab.png]]
244
245 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**. (If this folder doesn't appear, you may need to set your preferences to automatically generate these source files; see the second suggestion on [[http:~~/~~/wiki.wocommunity.org/display/documentation/Useful+Eclipse+or+WOLips+Preferences>>url:http://wiki.wocommunity.org/display/documentation/Useful+Eclipse+or+WOLips+Preferences||rel="nofollow" shape="rect" class="external-link"]].)
246
247
248
249 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.
250
251
252
253 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:
254
255 {{code}}
256 public String fullName() {
257 return this.firstName() + " " + this.lastName();
258 }
259
260 {{/code}}
261
262 Nothing fancy here. Now open **BlogEntry.java** and add the following method:
263
264 {{code}}
265 @Override
266 public void awakeFromInsertion(EOEditingContext editingContext) {
267 super.awakeFromInsertion(editingContext);
268 NSTimestamp now = new NSTimestamp();
269 setCreationDate(now);
270 setLastModified(now);
271 }
272
273 {{/code}}
274
275 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 and last modification dates without having the user to add those values.
276
277 Now, let's use migrations to actually create the database.
278
279 == Using migrations ==
280
281 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**.
282
283 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**.
284
285 Type **your.app.model.migrations** as the package and **BlogModel0** as the name of the class. Click **Finish**.
286
287 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.
288
289 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).
290
291 Remove the pound char in front of those two properties:
292
293 {{code}}
294 #er.migration.migrateAtStartup=true
295 #er.migration.createTablesIfNecessary=true
296
297 {{/code}}
298
299 After removing the pound char, the two properties should look like this:
300
301 {{code}}
302 er.migration.migrateAtStartup=true
303 er.migration.createTablesIfNecessary=true
304
305 {{/code}}
306
307 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:
308
309 {{code}}
310 BlogRest[62990] INFO er.extensions.migration.ERXMigrator - Upgrading BlogModel to version 0 with migration 'your.app.model.migrations.BlogModel0@4743bf3d'
311 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)
312 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE Author ADD PRIMARY KEY (id)
313 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)
314 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE BlogEntry ADD PRIMARY KEY (id)
315 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)
316 BlogRest[62990] DEBUG NSLog - evaluateExpression: <er.h2.jdbcadaptor.ERH2PlugIn$H2Expression: "UPDATE _dbupdater SET version = ? WHERE modelname = ?" withBindings: 1:0(version), 2:"BlogModel"(modelName)>
317
318 {{/code}}
319
320 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.
321
322 = Creating REST controllers and routes =
323
324 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.
325
326 By default, a REST route in ERRest will generate a link like this:
327
328 {{code}}
329 /cgi-bin/WebObjects/AppName.woa/ra/EntityName/id
330 {{/code}}
331
332 So for our case, to get the first blog posting from BlogRest, the URL will look like this:
333
334 {{code}}
335 /cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries/1.html
336 {{/code}}
337
338 {{info}}
339 You can shorten the URL by using mod_rewrite in Apache httpd
340 {{/info}}
341
342 == Creating controllers ==
343
344 ERRest needs controllers to act as a broker between working with the objects and the routes. So let's create a controller for BlogEntry.
345
346 Create a Java class named **BlogEntryController**, in the **your.app.rest.controllers** package, that will extend from **er.rest.routes.ERXDefaultRouteController**. Click **Finish**.
347
348 When you extend from **ERXDefaultRouteController**, a bunch of methods are added to the subclass. Let's see what they are for.
349
350 * **updateAction**: to update a specific instance of BlogEntry
351 * **destroyAction**: to delete a specific instance of BlogEntry
352 * **showAction**: to get one specific instance of BlogEntry
353 * **createAction**: to create a new object (a new instance of BlogEntry)
354 * **indexAction**: to list all (or a sublist) of the objects.
355
356 {{info}}
357 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.
358 {{/info}}
359
360 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)!
361
362 Add this method in **BlogEntryController**:
363
364 {{code}}
365 protected ERXKeyFilter filter() {
366 ERXKeyFilter personFilter = ERXKeyFilter.filterWithAttributes();
367 personFilter.setAnonymousUpdateEnabled(true);
368
369 ERXKeyFilter filter = ERXKeyFilter.filterWithAttributes();
370 filter.include(BlogEntry.AUTHOR, personFilter);
371 filter.setUnknownKeyIgnored(true);
372
373 return filter;
374 }
375
376 {{/code}}
377
378 Now, let's implement the **createAction** method:
379
380 {{code}}
381 public WOActionResults createAction() throws Throwable {
382 BlogEntry entry = create(filter());
383 editingContext().saveChanges();
384 return response(entry, filter());
385 }
386
387 {{/code}}
388
389 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?
390
391 Last step in the controller: implementing the **indexAction** method. Again, the code is simple:
392
393 {{code}}
394 public WOActionResults indexAction() throws Throwable {
395 NSArray<BlogEntry> entries = BlogEntry.fetchAllBlogEntries(editingContext());
396 return response(entries, filter());
397 }
398
399 {{/code}}
400
401 That code simply fetch all blog entries and return them in the response.
402
403 We can now go to the next step: adding the routes.
404
405 == Adding the routes ==
406
407 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:
408
409 {{code}}
410 ERXRouteRequestHandler restRequestHandler = new ERXRouteRequestHandler();
411 restRequestHandler.addDefaultRoutes(BlogEntry.ENTITY_NAME);
412 ERXRouteRequestHandler.register(restRequestHandler);
413 setDefaultRequestHandler(restRequestHandler);
414
415 {{/code}}
416
417 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.
418
419 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_>>url:http://youripsomeport||shape="rect"]]
420
421 == Adding posts and authors with curl ==
422
423 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.
424
425 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_>>url:http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa_||shape="rect"]], the full _curl// command will be:
426
427 {{code}}
428 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
429 {{/code}}
430
431 The response should look this:
432
433 {{code}}
434 HTTP/1.0 201 Apple WebObjects
435 Content-Length: 249
436 x-webobjects-loadaverage: 0
437 Content-Type: application/json
438
439 {"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"}}
440
441 {{/code}}
442
443 To get a list of blog entries:
444
445 {{code}}
446 curl -X GET http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.json
447
448 {{/code}}
449
450 You can stop the application and proceed to the next step.
451
452 == Adding HTML views for blog posts ==
453
454 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:
455
456 {{code}}
457 @Override
458 protected boolean isAutomaticHtmlRoutingEnabled() {
459 return true;
460 }
461
462 {{/code}}
463
464 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**.
465
466 The next step to get it to work is to make **BlogEntryIndexPage** to implement the **er.rest.routes.IERXRouteComponent** interface.
467
468 {{code}}
469 import er.rest.routes.IERXRouteComponent;
470
471 public class BlogEntryIndexPage extends WOComponent implements IERXRouteComponent {
472
473 {{/code}}
474
475 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:
476
477 {{code}}
478 public NSArray<BlogEntry> entries() {
479 EOEditingContext ec = ERXEC.newEditingContext();
480 return BlogEntry.fetchAllBlogEntries(ec, BlogEntry.CREATION_DATE.descs());
481 }
482
483 {{/code}}
484
485 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**:
486
487 {{code}}
488 private BlogEntry entryItem;
489
490 public BlogEntry entryItem() {
491 return entryItem;
492 }
493
494 public void setEntryItem(BlogEntry entryItem) {
495 this.entryItem = entryItem;
496 }
497
498 {{/code}}
499
500 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:
501
502 {{code}}
503 <wo:loop list="$entries" item="$entryItem">
504 <p><wo:str value="$entryItem.title" /></p>
505 <p><wo:str value="$entryItem.author.fullName" /></p>
506 </wo:loop>
507
508 {{/code}}
509
510 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.
511
512 If you go to [[http:~~/~~/192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.html>>url:http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.html||shape="rect"]], you will see the list of blog entries!
513
514 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**.
515
516 Open **BlogEntryShowPage.java** and make sure the class implements **er.rest.routes.IERXRouteComponent**.
517
518 {{code}}
519 import er.rest.routes.IERXRouteComponent;
520
521 public class BlogEntryShowPage extends WOComponent implements IERXRouteComponent {
522
523 {{/code}}
524
525 We need to add other methods to receive the BlogEntry object from the controller. In **BlogEntryShowPage.java**, add:
526
527 {{code}}
528 private BlogEntry blogEntry;
529
530 @ERXRouteParameter
531 public void setBlogEntry(BlogEntry blogEntryFromController) {
532 this.blogEntry = blogEntryFromController;
533 }
534
535 public BlogEntry blogEntry() {
536 return this.blogEntry;
537 }
538
539 {{/code}}
540
541 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//.
542
543 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:
544
545 {{code}}
546 <h1><wo:str value="$blogEntry.title" /></h1>
547 <p><wo:str value="$blogEntry.content" /></p>
548 <p>Created on: <wo:str value="$blogEntry.creationDate" dateformat="%Y/%m/%d" /></p>
549 <p>Added by: <wo:str value="$blogEntry.author.fullName" /></p>
550
551 {{/code}}
552
553 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:
554
555 {{code}}
556 <p><wo:str value="$entryItem.title" /></p>
557
558 {{/code}}
559
560 with:
561
562 {{code}}
563 <p><wo:ERXRouteLink entityName="BlogEntry" record="$entryItem" action="show"><wo:str value="$entryItem.title" /></wo:ERXRouteLink></p>
564
565 {{/code}}
566
567 Save the component and run the app. Go to [[http:~~/~~/192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.html>>url:http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.html||shape="rect"]] 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!
568
569 The REST part of this tutorial is now complete, [[you can now move to the next part of the tutorial>>doc:WEB.Home.Getting Started.Your First Framework.WebHome]].