Skip to Content

Wiki source code of Your First Rest Project

Version 30.1 by Pascal Robert on 2011/12/27 13:43
Show last authors
1 {{toc}}{{/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**. 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 |= Column name |= Type |= Constraints
24 | id | integer | primary key
25 | title | string(255) |
26 | content | string(4000) |
27 | lastModified | timestamp |
28 | creationDate | timestamp |
29 | author | integer | relation with Author
30
31 Author will have the following columns:
32
33 |= Column name |= Type |= Constraints
34 | id | integer | primary key
35 | firstName | string(50) |
36 | lastName | string(50) |
37 | email | string(100) | unique
38 | passwd | string(16) |
39
40 == Creating the EOModel ==
41
42 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).
43
44 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.
45
46 To create the EOModel, in the project right-click on the project name and select **New** > **EOModel**.
47
48 Name it **BlogModel** and in the plugin list, select **H2**. Click **Finish**.
49
50 The model should show up in a window that looks like this:
51
52 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.
53
54 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).
55
56 Now, right-click on **BlogModel** and select **New Entity**.
57
58 Type the following details in the **Basic** tab:
59
60 * **Name**: BlogEntry
61 * **Table Name**: BlogEntry
62 * **Class Name**: your.app.model.BlogEntry
63
64 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.
65
66 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:
67
68 * **Name**: title
69 * **Column**: title
70 * **Prototype**: varchar255
71
72 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.
73
74 Now, repeat the last two steps to create the other attributes for the **BlogEntry** entity, with the following values:
75
76 |= Attribute name |= Column |= Prototype
77 | content | content | longtext
78 | lastModified | lastModified | dateTime
79 | creationDate | creationDate | dateTime
80
81 If you did everything well, the list of attributes should look like this:
82
83 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 **lastModified** and **creationDate** attributes. The final list should look like this:
84
85 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:
86
87 |= Attribute name |= Column |= Prototype
88 | firstName | firstName | varchar50
89 | lastName | lastName | varchar50
90 | email | email | varchar100
91 | passwd | passwd | varchar16
92
93 Final list of attributes should look like this:
94
95 Now, it's time to link the two entities together. A 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 left, 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:
96
97 If you check in the **Outline** tab, you should see that **Author** now have a **blogEntries** relationship, and **BlogEntry** have a **author** relationship.
98
99 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**.
100
101 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.
102
103 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:
104
105 {{code}}
106
107 public String fullName() {
108 return this.firstName() + " " + this.lastName();
109 }
110
111 {{/code}}
112
113 Nothing fancy here. Now, let's use migrations to actually create the database.
114
115 == Using migrations ==
116
117 Migrations allow you to create the tables and columns (and some types of constraint). **Entity Modeler** have 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**.
118
119 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**.
120
121 Type **your.app.model.migrations** as the package and **BlogModel0** as the name of the class. Click **Finish**.
122
123 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.
124
125 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).
126
127 Remove the pound char in front of those two properties:
128
129 {{code}}
130
131 #er.migration.migrateAtStartup=true
132 #er.migration.createTablesIfNecessary=true
133
134 {{/code}}
135
136 After removing the pound char, the two properties should look like this:
137
138 {{code}}
139
140 er.migration.migrateAtStartup=true
141 er.migration.createTablesIfNecessary=true
142
143 {{/code}}
144
145 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:
146
147 {{code}}
148
149 BlogRest[62990] INFO er.extensions.migration.ERXMigrator - Upgrading BlogModel to version 0 with migration 'your.app.model.migrations.BlogModel0@4743bf3d'
150 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, passwd VARCHAR(16) NOT NULL)
151 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE Author ADD PRIMARY KEY (id)
152 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, lastModified TIMESTAMP NOT NULL, title VARCHAR(255) NOT NULL)
153 BlogRest[62990] INFO er.extensions.jdbc.ERXJDBCUtilities - Executing ALTER TABLE BlogEntry ADD PRIMARY KEY (id)
154 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)
155 BlogRest[62990] DEBUG NSLog - evaluateExpression: <er.h2.jdbcadaptor.ERH2PlugIn$H2Expression: "UPDATE _dbupdater SET version = ? WHERE modelname = ?" withBindings: 1:0(version), 2:"BlogModel"(modelName)>
156
157 {{/code}}
158
159 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.
160
161 = Creating REST controllers and routes =