Your First Rest Project

= Introduction =

6

7

In the first part of the Blog tutorial, you will learn:

8

9

* How to create a EOModel for the database (we will use H2)

10

* How to use migrations to create the database tables

11

* How to use ERRest to create blog posts with JSON format and how to display the blog posts in HTML for readers

12

13

= Create a new project =

14

15

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//.

16

17

= Create the database model =

18

19

== Database structure ==

20

21

We will build a small database model for the blog. The database will have two tables: BlogEntry and Author.

22

23

BlogEntry will have the following columns:

|=(((

Column name

)))|=(((

Type

)))|=(((

Constraints

)))

|(((

id

)))|(((

integer

)))|(((

primary key

)))

|(((

title

)))|(((

string(255)

)))|(((

)))

|(((

content

)))|(((

string(4000)

)))|(((

)))

|(((

creationDate

)))|(((

timestamp

)))|(((

)))

|(((

lastModified

)))|(((

timestamp

)))|(((

)))

|(((

author

)))|(((

integer

)))|(((

relation with Author

)))

Author will have the following columns:

|=(((

Column name

)))|=(((

Type

)))|=(((

Constraints

)))

|(((

id

)))|(((

integer

)))|(((

primary key

)))

|(((

firstName

)))|(((

string(50)

)))|(((

)))

|(((

lastName

)))|(((

string(50)

)))|(((

)))

|(((

email

)))|(((

string(100)

)))|(((

unique

)))

== Creating the EOModel ==

114

115

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).

116

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

119

To create the EOModel, in the project right-click on the project name and select **New** -> **EOModel**.

120

121

Name it **BlogModel** and in the plugin list, select **H2**. Click **Finish**.

122

123

The model should show up in a window that looks like this:

124

125

[[image:attach:EOModeler.png]]

126

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

129

In the Entity Modeler window, click on **Default**, and for the **URL** field, type

130

131

132

jdbc:h2:~/BlogTutorial

133

134

135

. When the database will be created, it will be stored in your home directory (/Users/youruser/ on OS X).

136

137

Now, right-click on **BlogModel** and select **New Entity**.

138

139

Type the following details in the **Basic** tab:

140

141

* **Name**: BlogEntry

142

* **Table Name**: BlogEntry

143

* **Class Name**: your.app.model.BlogEntry

144

145

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.

146

147

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:

* **Name**: title

* **Column**: title

* **Prototype**: varchar255

152

153

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.

154

155

Now, repeat the last two steps to create the other attributes for the **BlogEntry** entity, with the following values:

|=(((

Attribute name

)))|=(((

Column

)))|=(((

Prototype

)))

|(((

content

)))|(((

content

)))|(((

longtext

)))

|(((

creationDate

)))|(((

creationDate

)))|(((

dateTime

)))

|(((

lastModified

)))|(((

lastModified

)))|(((

dateTime

)))

If you did everything well, the list of attributes should look like this:

187

188

[[image:attach:list_wlock.png]]

189

190

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:

191

192

[[image:attach:list.png]]

193

194

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:

|=(((

Attribute name

)))|=(((

Column

)))|=(((

Prototype

)))

|(((

firstName

)))|(((

firstName

)))|(((

varchar50

)))

|(((

lastName

)))|(((

lastName

)))|(((

varchar50

)))

|(((

email

)))|(((

email

)))|(((

varchar100

)))

Final list of attributes should look like this:

226

227

[[image:attach:author_list.png]]

228

229

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:

230

231

If you check in the **Outline** tab, you should see that **Author** now have a **blogEntries** relationship, and **BlogEntry** have a **author** relationship.

232

233

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"]].)

234

235

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.

236

237

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:

238

239

240

public String fullName() {

241

return this.firstName() + " " + this.lastName();

}

Nothing fancy here. Now open **BlogEntry.java** and add the following method:

@Override

public void awakeFromInsertion(EOEditingContext editingContext) {

251

super.awakeFromInsertion(editingContext);

252

NSTimestamp now = new NSTimestamp();

253

setCreationDate(now);

254

setLastModified(now);

}

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.

260

261

Now, let's use migrations to actually create the database.

262

263

== Using migrations ==

264

265

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**.

266

267

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**.

268

269

Type **your.app.model.migrations** as the package and **BlogModel0** as the name of the class. Click **Finish**.

270

271

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.

272

273

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).

274

275

Remove the pound char in front of those two properties:

276

277

278

#er.migration.migrateAtStartup=true

279

#er.migration.createTablesIfNecessary=true

After removing the pound char, the two properties should look like this:

284

285

286

er.migration.migrateAtStartup=true

287

er.migration.createTablesIfNecessary=true

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:

292

293

294

BlogRest[62990] INFO er.extensions.migration.ERXMigrator - Upgrading BlogModel to version 0 with migration 'your.app.model.migrations.BlogModel0@4743bf3d'

295

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)

296

BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE Author ADD PRIMARY KEY (id)

297

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)

298

BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE BlogEntry ADD PRIMARY KEY (id)

299

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)

300

BlogRest[62990] DEBUG NSLog - evaluateExpression: <er.h2.jdbcadaptor.ERH2PlugIn$H2Expression: "UPDATE _dbupdater SET version = ? WHERE modelname = ?" withBindings: 1:0(version), 2:"BlogModel"(modelName)>

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.

305

306

= Creating REST controllers and routes =

307

308

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.

309

310

By default, a REST route in ERRest will generate a link like this:

311

312

313

/cgi-bin/WebObjects/AppName.woa/ra/EntityName/id

314

315

316

So for our case, to get the first blog posting from BlogRest, the URL will look like this:

317

318

319

/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries/1.html

You can shorten the URL by using mod_rewrite in Apache httpd

324

325

326

== Creating controllers ==

327

328

ERRest needs controllers to act as a broker between working with the objects and the routes. So let's create a controller for BlogEntry.

329

330

Create a Java class named **BlogEntryController**, in the **your.app.rest.controllers** package, that will extend from **er.rest.routes.ERXDefaultRouteController**. Click **Finish**.

331

332

When you extend from **ERXDefaultRouteController**, a bunch of methods are added to the subclass. Let's see what they are for.

333

334

* **updateAction**: to update a specific instance of BlogEntry

335

* **destroyAction**: to delete a specific instance of BlogEntry

336

* **showAction**: to get one specific instance of BlogEntry

337

* **createAction**: to create a new object (a new instance of BlogEntry)

338

* **indexAction**: to list all (or a sublist) of the objects.

339

340

341

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.

342

343

344

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)!

345

346

Add this method in **BlogEntryController**:

347

348

349

protected ERXKeyFilter filter() {

350

ERXKeyFilter personFilter = ERXKeyFilter.filterWithAttributes();

351

personFilter.setAnonymousUpdateEnabled(true);

352

353

ERXKeyFilter filter = ERXKeyFilter.filterWithAttributes();

354

filter.include(BlogEntry.AUTHOR, personFilter);

355

filter.setUnknownKeyIgnored(true);

return filter;

}

Now, let's implement the **createAction** method:

363

364

365

public WOActionResults createAction() throws Throwable {

366

BlogEntry entry = create(filter());

367

editingContext().saveChanges();

368

return response(entry, filter());

}

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?

374

375

Last step in the controller: implementing the **indexAction** method. Again, the code is simple:

376

377

378

public WOActionResults indexAction() throws Throwable {

379

NSArray<BlogEntry> entries = BlogEntry.fetchAllBlogEntries(editingContext());

380

return response(entries, filter());

}

That code simply fetch all blog entries and return them in the response.

386

387

We can now go to the next step: adding the routes.

388

389

== Adding the routes ==

390

391

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:

392

393

394

ERXRouteRequestHandler restRequestHandler = new ERXRouteRequestHandler();

395

restRequestHandler.addDefaultRoutes(BlogEntry.ENTITY_NAME);

396

ERXRouteRequestHandler.register(restRequestHandler);

397

setDefaultRequestHandler(restRequestHandler);

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.

402

403

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"]]

404

405

== Adding posts and authors with curl ==

406

407

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.

408

409

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:

410

411

412

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

413

414

415

The response should look this:

416

417

418

HTTP/1.0 201 Apple WebObjects

419

Content-Length: 249

420

x-webobjects-loadaverage: 0

421

Content-Type: application/json

422

423

{"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"}}

To get a list of blog entries:

428

429

430

curl -X GET http://192.168.0.102:52406/cgi-bin/WebObjects/BlogRest.woa/ra/blogEntries.json

You can stop the application and proceed to the next step.

435

436

== Adding HTML views for blog posts ==

437

438

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:

@Override

protected boolean isAutomaticHtmlRoutingEnabled() {

return true;

}

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**.

449

450

The next step to get it to work is to make **BlogEntryIndexPage** to implement the **er.rest.routes.IERXRouteComponent** interface.

451

452

453

import er.rest.routes.IERXRouteComponent;

454

455

public class BlogEntryIndexPage extends WOComponent implements IERXRouteComponent {

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:

460

461

462

public NSArray<BlogEntry> entries() {

463

EOEditingContext ec = ERXEC.newEditingContext();

464

return BlogEntry.fetchAllBlogEntries(ec, BlogEntry.CREATION_DATE.descs());

}

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**:

470

471

472

private BlogEntry entryItem;

473

474

public BlogEntry entryItem() {

return entryItem;

}

public void setEntryItem(BlogEntry entryItem) {

479

this.entryItem = entryItem;

}

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:

485

486

487

<wo:loop list="$entries" item="$entryItem">

488

<wo:str value="$entryItem.title" />

489

<wo:str value="$entryItem.author.fullName" />

</wo:loop>

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.

495

496

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!

497

498

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**.

499

500

Open **BlogEntryShowPage.java** and make sure the class implements **er.rest.routes.IERXRouteComponent**.

501

502

503

import er.rest.routes.IERXRouteComponent;

504

505

public class BlogEntryShowPage extends WOComponent implements IERXRouteComponent {

We need to add other methods to receive the BlogEntry object from the controller. In **BlogEntryShowPage.java**, add:

510

511

512

private BlogEntry blogEntry;

513

514

@ERXRouteParameter

515

public void setBlogEntry(BlogEntry blogEntryFromController) {

516

this.blogEntry = blogEntryFromController;

517

}

518

519

public BlogEntry blogEntry() {

520

return this.blogEntry;

}

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//.

526

527

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:

<wo:str value="$blogEntry.content" />

532

Created on: <wo:str value="$blogEntry.creationDate" dateformat="%Y/%m/%d" />

533

Added by: <wo:str value="$blogEntry.author.fullName" />

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:

538

539

540

<wo:str value="$entryItem.title" />

with:

<wo:ERXRouteLink entityName="BlogEntry" record="$entryItem" action="show"><wo:str value="$entryItem.title" /></wo:ERXRouteLink>

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!

552

553

The REST part of this tutorial is now complete, [[you can now move to the next part of the tutorial>>doc:Your First Framework]].

Wiki source code of Your First Rest Project

Applications

Navigation

My Recent Modifications

Need help?