Changes for page Your First Rest Project

Summary

• Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.filippolauria
	1	+XWiki.steffan

Content

...	...	@@ -1,7 +1,5 @@
	1	+{{toc}}{{/toc}}
1	1
2		-
3		-{{toc/}}
4		-
5	5	= Introduction =
6	6
7	7	In the first part of the Blog tutorial, you will learn:
...	...	@@ -22,93 +22,21 @@
22	22
23	23	BlogEntry will have the following columns:
24	24
25		-|=(((
26		-Column name
27		-)))|=(((
28		-Type
29		-)))|=(((
30		-Constraints
31		-)))
32		-|(((
33		-id
34		-)))|(((
35		-integer
36		-)))|(((
37		-primary key
38		-)))
39		-|(((
40		-title
41		-)))|(((
42		-string(255)
43		-)))|(((
44		-
45		-)))
46		-|(((
47		-content
48		-)))|(((
49		-string(4000)
50		-)))|(((
51		-
52		-)))
53		-|(((
54		-creationDate
55		-)))|(((
56		-timestamp
57		-)))|(((
58		-
59		-)))
60		-|(((
61		-lastModified
62		-)))|(((
63		-timestamp
64		-)))|(((
65		-
66		-)))
67		-|(((
68		-author
69		-)))|(((
70		-integer
71		-)))|(((
72		-relation with Author
73		-)))
	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
74	74
75	75	Author will have the following columns:
76	76
77		-|=(((
78		-Column name
79		-)))|=(((
80		-Type
81		-)))|=(((
82		-Constraints
83		-)))
84		-|(((
85		-id
86		-)))|(((
87		-integer
88		-)))|(((
89		-primary key
90		-)))
91		-|(((
92		-firstName
93		-)))|(((
94		-string(50)
95		-)))|(((
96		-
97		-)))
98		-|(((
99		-lastName
100		-)))|(((
101		-string(50)
102		-)))|(((
103		-
104		-)))
105		-|(((
106		-email
107		-)))|(((
108		-string(100)
109		-)))|(((
110		-unique
111		-)))
	33	+|= Column name |= Type |= Constraints
	34	+| id | integer | primary key
	35	+| firstName | string(50) |
	36	+| lastName | string(50) |
	37	+| email | string(100) | unique
112	112
113	113	== Creating the EOModel ==
114	114
...	...	@@ -116,24 +116,16 @@
116	116
117	117	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.
118	118
119		-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**.
120	120
121	121	Name it **BlogModel** and in the plugin list, select **H2**. Click **Finish**.
122	122
123	123	The model should show up in a window that looks like this:
124	124
125		-[[image:attach:EOModeler.png]]
126		-
127	127	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.
128	128
129		-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).
130	130
131		-{{code}}
132		-jdbc:h2:~/BlogTutorial
133		-{{/code}}
134		-
135		-. When the database will be created, it will be stored in your home directory (/Users/youruser/ on OS X).
136		-
137	137	Now, right-click on **BlogModel** and select **New Entity**.
138	138
139	139	Type the following details in the **Basic** tab:
...	...	@@ -154,34 +154,10 @@
154	154
155	155	Now, repeat the last two steps to create the other attributes for the **BlogEntry** entity, with the following values:
156	156
157		-|=(((
158		-Attribute name
159		-)))|=(((
160		-Column
161		-)))|=(((
162		-Prototype
163		-)))
164		-|(((
165		-content
166		-)))|(((
167		-content
168		-)))|(((
169		-longtext
170		-)))
171		-|(((
172		-creationDate
173		-)))|(((
174		-creationDate
175		-)))|(((
176		-dateTime
177		-)))
178		-|(((
179		-lastModified
180		-)))|(((
181		-lastModified
182		-)))|(((
183		-dateTime
184		-)))
	75	+|= Attribute name |= Column |= Prototype
	76	+| content | content | longtext
	77	+| creationDate | creationDate | dateTime
	78	+| lastModified | lastModified | dateTime
185	185
186	186	If you did everything well, the list of attributes should look like this:
187	187
...	...	@@ -189,34 +189,10 @@
189	189
190	190	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:
191	191
192		-|=(((
193		-Attribute name
194		-)))|=(((
195		-Column
196		-)))|=(((
197		-Prototype
198		-)))
199		-|(((
200		-firstName
201		-)))|(((
202		-firstName
203		-)))|(((
204		-varchar50
205		-)))
206		-|(((
207		-lastName
208		-)))|(((
209		-lastName
210		-)))|(((
211		-varchar50
212		-)))
213		-|(((
214		-email
215		-)))|(((
216		-email
217		-)))|(((
218		-varchar100
219		-)))
	86	+|= Attribute name |= Column |= Prototype
	87	+| firstName | firstName | varchar50
	88	+| lastName | lastName | varchar50
	89	+| email | email | varchar100
220	220
221	221	Final list of attributes should look like this:
222	222
...	...	@@ -224,13 +224,14 @@
224	224
225	225	If you check in the **Outline** tab, you should see that **Author** now have a **blogEntries** relationship, and **BlogEntry** have a **author** relationship.
226	226
227		-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**.
228	228
229		-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.
230	230
231	231	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:
232	232
233	233	{{code}}
	104	+
234	234	public String fullName() {
235	235	return this.firstName() + " " + this.lastName();
236	236	}
...	...	@@ -240,6 +240,7 @@
240	240	Nothing fancy here. Now open **BlogEntry.java** and add the following method:
241	241
242	242	{{code}}
	114	+
243	243	@Override
244	244	public void awakeFromInsertion(EOEditingContext editingContext) {
245	245	super.awakeFromInsertion(editingContext);
...	...	@@ -269,6 +269,7 @@
269	269	Remove the pound char in front of those two properties:
270	270
271	271	{{code}}
	144	+
272	272	#er.migration.migrateAtStartup=true
273	273	#er.migration.createTablesIfNecessary=true
274	274
...	...	@@ -277,14 +277,16 @@
277	277	After removing the pound char, the two properties should look like this:
278	278
279	279	{{code}}
	153	+
280	280	er.migration.migrateAtStartup=true
281	281	er.migration.createTablesIfNecessary=true
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}}
	162	+
288	288	BlogRest[62990] INFO er.extensions.migration.ERXMigrator - Upgrading BlogModel to version 0 with migration 'your.app.model.migrations.BlogModel0@4743bf3d'
289	289	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)
290	290	BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE Author ADD PRIMARY KEY (id)
...	...	@@ -295,7 +295,7 @@
295	295
296	296	{{/code}}
297	297
298		-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.
299	299
300	300	= Creating REST controllers and routes =
301	301
...	...	@@ -332,14 +332,15 @@
332	332	* **indexAction**: to list all (or a sublist) of the objects.
333	333
334	334	{{info}}
335		-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.
336	336	{{/info}}
337	337
338		-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)
339	339
340	340	Add this method in **BlogEntryController**:
341	341
342	342	{{code}}
	218	+
343	343	protected ERXKeyFilter filter() {
344	344	ERXKeyFilter personFilter = ERXKeyFilter.filterWithAttributes();
345	345	personFilter.setAnonymousUpdateEnabled(true);
...	...	@@ -356,6 +356,7 @@
356	356	Now, let's implement the **createAction** method:
357	357
358	358	{{code}}
	235	+
359	359	public WOActionResults createAction() throws Throwable {
360	360	BlogEntry entry = create(filter());
361	361	editingContext().saveChanges();
...	...	@@ -369,6 +369,7 @@
369	369	Last step in the controller: implementing the **indexAction** method. Again, the code is simple:
370	370
371	371	{{code}}
	249	+
372	372	public WOActionResults indexAction() throws Throwable {
373	373	NSArray<BlogEntry> entries = BlogEntry.fetchAllBlogEntries(editingContext());
374	374	return response(entries, filter());
...	...	@@ -385,6 +385,7 @@
385	385	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:
386	386
387	387	{{code}}
	266	+
388	388	ERXRouteRequestHandler restRequestHandler = new ERXRouteRequestHandler();
389	389	restRequestHandler.addDefaultRoutes(BlogEntry.ENTITY_NAME);
390	390	ERXRouteRequestHandler.register(restRequestHandler);
...	...	@@ -394,13 +394,13 @@
394	394
395	395	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.
396	396
397		-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"]]
	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_]]//
398	398
399	399	== Adding posts and authors with curl ==
400	400
401	401	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.
402	402
403		-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:
404	404
405	405	{{code}}
406	406	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
...	...	@@ -409,6 +409,7 @@
409	409	The response should look this:
410	410
411	411	{{code}}
	291	+
412	412	HTTP/1.0 201 Apple WebObjects
413	413	Content-Length: 249
414	414	x-webobjects-loadaverage: 0
...	...	@@ -421,6 +421,7 @@
421	421	To get a list of blog entries:
422	422
423	423	{{code}}
	304	+
424	424	curl -X GET http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.json
425	425
426	426	{{/code}}
...	...	@@ -432,6 +432,7 @@
432	432	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:
433	433
434	434	{{code}}
	316	+
435	435	@Override
436	436	protected boolean isAutomaticHtmlRoutingEnabled() {
437	437	return true;
...	...	@@ -439,11 +439,12 @@
439	439
440	440	{{/code}}
441	441
442		-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**.
443	443
444	444	The next step to get it to work is to make **BlogEntryIndexPage** to implement the **er.rest.routes.IERXRouteComponent** interface.
445	445
446	446	{{code}}
	329	+
447	447	import er.rest.routes.IERXRouteComponent;
448	448
449	449	public class BlogEntryIndexPage extends WOComponent implements IERXRouteComponent {
...	...	@@ -453,6 +453,7 @@
453	453	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:
454	454
455	455	{{code}}
	339	+
456	456	public NSArray<BlogEntry> entries() {
457	457	EOEditingContext ec = ERXEC.newEditingContext();
458	458	return BlogEntry.fetchAllBlogEntries(ec, BlogEntry.CREATION_DATE.descs());
...	...	@@ -463,6 +463,7 @@
463	463	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**:
464	464
465	465	{{code}}
	350	+
466	466	private BlogEntry entryItem;
467	467
468	468	public BlogEntry entryItem() {
...	...	@@ -478,6 +478,7 @@
478	478	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:
479	479
480	480	{{code}}
	366	+
481	481	<wo:loop list="$entries" item="$entryItem">
482	482	<p><wo:str value="$entryItem.title" /></p>
483	483	<p><wo:str value="$entryItem.author.fullName" /></p>
...	...	@@ -487,13 +487,14 @@
487	487
488	488	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.
489	489
490		-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
491	491
492	492	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**.
493	493
494		-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**.
495	495
496	496	{{code}}
	383	+
497	497	import er.rest.routes.IERXRouteComponent;
498	498
499	499	public class BlogEntryShowPage extends WOComponent implements IERXRouteComponent {
...	...	@@ -503,6 +503,7 @@
503	503	We need to add other methods to receive the BlogEntry object from the controller. In **BlogEntryShowPage.java**, add:
504	504
505	505	{{code}}
	393	+
506	506	private BlogEntry blogEntry;
507	507
508	508	@ERXRouteParameter
...	...	@@ -521,6 +521,7 @@
521	521	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:
522	522
523	523	{{code}}
	412	+
524	524	<h1><wo:str value="$blogEntry.title" /></h1>
525	525	<p><wo:str value="$blogEntry.content" /></p>
526	526	<p>Created on: <wo:str value="$blogEntry.creationDate" dateformat="%Y/%m/%d" /></p>
...	...	@@ -531,6 +531,7 @@
531	531	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:
532	532
533	533	{{code}}
	423	+
534	534	<p><wo:str value="$entryItem.title" /></p>
535	535
536	536	{{/code}}
...	...	@@ -538,10 +538,11 @@
538	538	with:
539	539
540	540	{{code}}
	431	+
541	541	<p><wo:ERXRouteLink entityName="BlogEntry" record="$entryItem" action="show"><wo:str value="$entryItem.title" /></wo:ERXRouteLink></p>
542	542
543	543	{{/code}}
544	544
545		-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
546	546
547		-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]].