-
Notifications
You must be signed in to change notification settings - Fork 0
/
intro.html
327 lines (323 loc) · 10.6 KB
/
intro.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>exedio persistence - Introduction Trail</title>
<meta name="keywords" content="Persistence, Java">
<meta name="description" content="persistence framework for java">
<link rel="stylesheet" href="cope.css">
</head>
<body>
<!-- HEADER -->
<div id="header_wrap" class="outer">
<header class="inner">
<a id="forkme_banner" href="https://github.com/exedio">View on GitHub</a>
<h1 id="project_title">exedio persistence</h1>
<h2 id="project_tagline">Persistence Framework for Java.</h2>
<a id="toplink" href="index.html">Go to top</a>
</header>
</div>
<!-- MAIN CONTENT -->
<div id="main_content_wrap" class="outer">
<section id="main_content" class="inner">
<h2>Introduction Trail</h2>
<p>
This is the initial trail of the documentation trails.
It gives you a step-by-step introduction into the persistence framework.
</p>
<p>
If you already decided to use exedio persistence for a project,
you may want to use the demoshop as a template.
This way you can skip most of the steps described here.
The demoshop is available under the
<a href="https://opensource.org/licenses/mit-license.php">The MIT License</a>.
<br>
<a href="http://sourceforge.net/project/showfiles.php?group_id=152867">Download</a>
</p>
<h3 id="contents">Contents</h3>
<ul>
<li><a href="#item">Your first item</a></li>
<li><a href="#instrument">Setting up the instrumentor</a></li>
<li><a href="#results">Results of the instrumentor</a></li>
<li><a href="#run">Make it run</a></li>
<li><a href="#further">Further Reading</a></li>
</ul>
<h3 id="item">Your first item</h3>
<p>
Creating a new persistent class is
as easy as creating any java class.
Make sure, the class extends <a href="api/com/exedio/cope/Item.html">Item</a>:
</p>
<pre>
class Customer extends <a href="api/com/exedio/cope/Item.html">Item</a>
{
}
</pre>
<p>
Now a persistent class isn't very useful
without any persistent fields,
so we also create our first one.
To do this we declare a static final constant
of the type <a href="api/com/exedio/cope/StringField.html">StringField</a>.
</p>
<pre>
class Customer extends <a href="api/com/exedio/cope/Item.html">Item</a>
{
static final <a href="api/com/exedio/cope/StringField.html">StringField</a> email = new <a href="api/com/exedio/cope/StringField.html#<init>()">StringField</a>();
}
</pre>
<p>
Thats the way you declare persistent classes and fields.
Now we have to setup the source code instrumentor.
</p>
<h3 id="instrument">Setting up the instrumentor</h3>
<p>
The instrumentor inserts a few methods and constructors into your
source code, so you don't have to write it on your own.
Don't worry, your code and the code generated by the instrumentor
will peacefully coexist.
</p>
<p>
Put a copy of
<code>exedio-cope.jar</code>,
<code>exedio-cope-instrument.jar</code>,
<code>trove.jar</code> and
<code>bsh-core.jar</code>
into the directory where you keep your third-party libraries.
In the following we assume, this is <code>lib</code>.
</p>
<p>
Next we have to include the code instrumentor into your build process.
Here we explain this for a build process managed by
<a href="https://ant.apache.org/">apache ant</a>.
We assume, that there is already a target <code>compile</code> which compiles
your projects sources including class <code>Customer</code> created above
located in directory <code>src</code>.
Put the following into your <code>build.xml</code>
</p>
<pre>
<taskdef name="instrument"
classname="com.exedio.cope.instrument.AntTask">
<classpath>
<pathelement location="<i>lib/exedio-cope-instrument.jar</i>" />
</classpath>
</taskdef>
<target name="instrument">
<instrument verbose="false">
<fileset dir="<i>${basedir}/src</i>">
<include name="*.java" />
</fileset>
</instrument>
</target>
</pre>
<p>
Parts in <code><i>italics</i></code> need to be adapted to your
directory layout.
Make target <code>compile</code> depend on target <code>instrument</code> and
add <code>lib/exedio-cope.jar</code> to the classpath of the <code>javac</code> task.
</p>
<p>
Now the instrumentor is ready to run.
On the command line type <code>ant instrument</code>.
</p>
<h3 id="results">Results of the instrumentor</h3>
<p>
After running the instrumentor,
the class <code>Customer</code> contains a few more methods and constructors.
Lets have a look, what these are useful for.
</p>
<p>
The first one in the <i>default creation constructor</i>:
</p>
<pre>
Customer(String email)
{
this(new SetValue[]{Customer.email.map(email)});
}
</pre>
<p>
It creates a new customer and sets the initial value of the field
<code>email</code> for that customer.
Note, for brevity the code snippet above does not include
javadoc comments generated by the instrumentor.
</p>
<p>
Next one is the generic creation constructor:
</p>
<pre>
Customer(SetValue[] setValues)
{
super(setValue);
}
</pre>
<p>
It creates a new customer and sets the initial values for any set of fields
for that customer.
This comes handy if there are more fields in class Customer,
since by default not all fields are set by the <i>default creation constructor</i>.
</p>
<p>
Next one is the <i>activation constructor</i>:
</p>
<pre>
Customer(<a href="api/com/exedio/cope/ActivationParameters.html">ActivationParameters</a> ap)
{
<a href="api/com/exedio/cope/Item.html#<init>(com.exedio.cope.ActivationParameters)">super</a>(ap);
}
</pre>
<p>
All you need to know about this for now is,
that the framework uses this constructor internally and you don't have to care about.
This constructor is one of the few things the framework has to demand for all persistent classes.
</p>
<p>
Next are the <i>field getter</i>
and <i>field setter</i> for the field <code>email</code>:
</p>
<pre>
String getEmail()
{
return email.get(this);
}
void setEmail(String email)
{
Customer.email.set(this, email);
}
</pre>
<p>
These allow convenient read/write access to the values of the field,
after the creation of the item.
</p>
<p>
Last but not least there is the <i>type constant</i>:
</p>
<pre>
static final Type<Customer> TYPE =
newType(Customer.class);
</pre>
<p>
This is useful for all sorts of things,
most prominently searching the database.
For instance searching for all customers is as easy as
<code>Customer.TYPE.<a href="api/com/exedio/cope/Type.html#search()">search</a>()</code>,
which returns a <code>List<Customer></code>.
More on this in the <a href="searching.html">Searching Trail</a>.
</p>
<p>
Next we will really store some persistent data.
</p>
<h3 id="run">Make it run</h3>
<p>
First we have to tell the framework,
which persistent types are to be maintained by the project.
For now this will be type <code>Customer</code> only.
So we write a new class <code>Main</code>:
</p>
<pre>
class Main
{
static final <a href="api/com/exedio/cope/Model.html">Model</a> model = new <a href="api/com/exedio/cope/Model.html#<init>(com.exedio.cope.Type...)">Model</a>(
Customer.TYPE
);
}
</pre>
<p>
Of course, if you already have some central kind of main class,
you can use this instead of writing a new one.
Just make sure, that all your persistent types show up in the list.
</p>
<p>
Next we will setup the database connection to be used by exedio persistence.
First put a jdbc driver
(i.e. <code>hsqldb.jar</code> or <code>mysql-connector-bin-3.1.12.jar</code>)
in your classpath.
</p>
<p>
Then create a file <code>cope.properties</code> with the following
contents for hsqldb:
</p>
<pre>
connection.url=jdbc:hsqldb:mem:copetest
connection.username=sa
connection.password=
</pre>
<p>
or alternativly for mysql:
</p>
<pre>
connection.url=jdbc:mysql://<i>localhost</i>/<i>copetest</i>
connection.username=<i>user</i>
connection.password=<i>password</i>
</pre>
<p>
Parts in <code><i>italics</i></code> need to be adapted to your database.
For mysql make sure, that the database does exist (<code>create database copetest</code>)
and is accessible for the user.
</p>
<p>
Finally we can add a main method to class <code>Main</code>,
that creates a customer in the database.
</p>
<pre>
public static void main(String[] args)
{
model.<a href="api/com/exedio/cope/Model.html#connect(com.exedio.cope.ConnectProperties)">connect</a>(
new <a href="api/com/exedio/cope/ConnectProperties.html#<init>(java.io.File)">ConnectProperties</a>(new File("cope.properties")));
model.createDatabase();
model.startTransaction();
Customer c = new Customer("[email protected]");
System.out.println("email:"+c.getEmail());
c.setEmail("[email protected]");
System.out.println("email2:"+c.getEmail());
model.commit();
}
</pre>
<p>
The call to <code>createDatabase</code> builds the schema of the database.
For this example it issues an sql statement like
<code>create table Customer ( email varchar(100) )</code>
to the database.
Note, that for mysql the main method work once only.
On any subsequent calls <code>createDatabase</code> fails,
because table <code>Customer</code> already exists.
On hsqldb the method work multiple times,
because the database is in-memory only.
</p>
<h3 id="further">Further Reading</h3>
<p>
This was the initial trail of the tour.
You may now proceed to the following trails:
</p>
<ul>
<li>
<a href="fields.html">Field Trail</a>
tells you about fields beyond the string field covered by this trail.
</li>
<li>
<a href="transactions.html">Transactions Trail</a>
tells you all about that Model.startTransaction() mentioned above.
</li>
<li>
<a href="webapplications.html">Web Application Trail</a>
shows you the little differences when using exedio persistence within a web container.
</li>
</ul>
</section>
</div>
<!-- FOOTER -->
<div id="footer_wrap" class="outer">
<footer class="inner">
<p>
Maintained by
<a href="https://www.exedio.com/" target="_top">exedio</a>
Gesellschaft für Softwareentwicklung mbH.
</p>
<a href="https://validator.w3.org/check?uri=referer" class="validhtml">Valid HTML5</a>
<p>
Slate theme by <a href="https://github.com/jasoncostello">Jason Costello</a>.
Published with <a href="https://pages.github.com">GitHub Pages</a>.
</p>
</footer>
</div>
</body>
</html>