Skip to Content

Changes for page Your First Rest Project

Last modified by Steve Peery on 2013/09/06 11:02
From version 19.1
edited by skcodes
on 2013/05/13 12:53
Change comment: Migrated to Confluence 4.0
To version 24.1
edited by steffan
on 2013/02/10 18:44
Change comment: Fix validation error when POSTing a blog entry by setting lastModified value

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.skcodes
1 +XWiki.steffan
Content
... ... @@ -1,4 +1,4 @@
1 -{{toc/}}
1 +{{toc}}{{/toc}}
2 2  
3 3  = Introduction =
4 4  
... ... @@ -20,93 +20,21 @@
20 20  
21 21  BlogEntry will have the following columns:
22 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 -)))
23 +|= Column name |= Type |= Constraints
24 +| id | integer | primary key
25 +| title | string(255) |
26 +| content | string(4000) |
27 +| creationDate | timestamp |
28 +| lastModified | timestamp |
29 +| author | integer | relation with Author
72 72  
73 73  Author will have the following columns:
74 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 -)))
33 +|= Column name |= Type |= Constraints
34 +| id | integer | primary key
35 +| firstName | string(50) |
36 +| lastName | string(50) |
37 +| email | string(100) | unique
110 110  
111 111  == Creating the EOModel ==
112 112  
... ... @@ -114,7 +114,7 @@
114 114  
115 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 116  
117 -To create the EOModel, in the project right-click on the project name and select **New** -> **EOModel**.
45 +To create the EOModel, in the project right-click on the project name and select **New** > **EOModel**.
118 118  
119 119  Name it **BlogModel** and in the plugin list, select **H2**. Click **Finish**.
120 120  
... ... @@ -122,14 +122,8 @@
122 122  
123 123  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.
124 124  
125 -In the Entity Modeler window, click on **Default**, and for the **URL** field, type
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).
126 126  
127 -{{code}}
128 -jdbc:h2:~/BlogTutorial
129 -{{/code}}
130 -
131 -. When the database will be created, it will be stored in your home directory (/Users/youruser/ on OS X).
132 -
133 133  Now, right-click on **BlogModel** and select **New Entity**.
134 134  
135 135  Type the following details in the **Basic** tab:
... ... @@ -150,34 +150,10 @@
150 150  
151 151  Now, repeat the last two steps to create the other attributes for the **BlogEntry** entity, with the following values:
152 152  
153 -|=(((
154 -Attribute name
155 -)))|=(((
156 -Column
157 -)))|=(((
158 -Prototype
159 -)))
160 -|(((
161 -content
162 -)))|(((
163 -content
164 -)))|(((
165 -longtext
166 -)))
167 -|(((
168 -creationDate
169 -)))|(((
170 -creationDate
171 -)))|(((
172 -dateTime
173 -)))
174 -|(((
175 -lastModified
176 -)))|(((
177 -lastModified
178 -)))|(((
179 -dateTime
180 -)))
75 +|= Attribute name |= Column |= Prototype
76 +| content | content | longtext
77 +| creationDate | creationDate | dateTime
78 +| lastModified | lastModified | dateTime
181 181  
182 182  If you did everything well, the list of attributes should look like this:
183 183  
... ... @@ -185,34 +185,10 @@
185 185  
186 186  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:
187 187  
188 -|=(((
189 -Attribute name
190 -)))|=(((
191 -Column
192 -)))|=(((
193 -Prototype
194 -)))
195 -|(((
196 -firstName
197 -)))|(((
198 -firstName
199 -)))|(((
200 -varchar50
201 -)))
202 -|(((
203 -lastName
204 -)))|(((
205 -lastName
206 -)))|(((
207 -varchar50
208 -)))
209 -|(((
210 -email
211 -)))|(((
212 -email
213 -)))|(((
214 -varchar100
215 -)))
86 +|= Attribute name |= Column |= Prototype
87 +| firstName | firstName | varchar50
88 +| lastName | lastName | varchar50
89 +| email | email | varchar100
216 216  
217 217  Final list of attributes should look like this:
218 218  
... ... @@ -220,9 +220,9 @@
220 220  
221 221  If you check in the **Outline** tab, you should see that **Author** now have a **blogEntries** relationship, and **BlogEntry** have a **author** relationship.
222 222  
223 -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"]].)
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**.
224 224  
225 -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.
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.
226 226  
227 227  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:
228 228  
... ... @@ -282,7 +282,7 @@
282 282  
283 283  {{/code}}
284 284  
285 -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:
159 +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:
286 286  
287 287  {{code}}
288 288  
... ... @@ -296,7 +296,7 @@
296 296  
297 297  {{/code}}
298 298  
299 -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.
173 +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.
300 300  
301 301  = Creating REST controllers and routes =
302 302  
... ... @@ -333,10 +333,10 @@
333 333  * **indexAction**: to list all (or a sublist) of the objects.
334 334  
335 335  {{info}}
336 -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.
210 +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.
337 337  {{/info}}
338 338  
339 -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)!
213 +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)
340 340  
341 341  Add this method in **BlogEntryController**:
342 342  
... ... @@ -399,13 +399,13 @@
399 399  
400 400  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.
401 401  
402 -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://yourip:someport/cgi-bin/WebObjects/BlogRest.woa_||shape="rect"]]
276 +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_]]//
403 403  
404 404  == Adding posts and authors with curl ==
405 405  
406 406  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.
407 407  
408 -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:
282 +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:
409 409  
410 410  {{code}}
411 411  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
... ... @@ -447,7 +447,7 @@
447 447  
448 448  {{/code}}
449 449  
450 -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**.
324 +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**.
451 451  
452 452  The next step to get it to work is to make **BlogEntryIndexPage** to implement the **er.rest.routes.IERXRouteComponent** interface.
453 453  
... ... @@ -499,11 +499,11 @@
499 499  
500 500  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.
501 501  
502 -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!
376 +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
503 503  
504 504  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**.
505 505  
506 -Open **BlogEntryShowPage.java** and make sure the class implements **er.rest.routes.IERXRouteComponent**.
380 +Open **BlogEntryShowPage.java** and make sure the class implements&nbsp;**er.rest.routes.IERXRouteComponent**.
507 507  
508 508  {{code}}
509 509  
... ... @@ -559,6 +559,6 @@
559 559  
560 560  {{/code}}
561 561  
562 -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!
436 +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
563 563  
564 -The REST part of this tutorial is now complete, [[you can now move to the next part of the tutorial>>doc:Your First Framework]].
438 +The REST part of this tutorial is now complete, [[you can now move to the next part of the tutorial>>Your First Framework]].