XWiki Android Project (Design.XWikiAndroid)

author	version	line-number	content
1	{{include document="XWiki.DesignClassSheet"/}}
2
3	This page is for future development and ideas about XWiki Android tools.
4
5	See current state at [[extensions:Extension.Google Android Client]].
6
7	(((
8	= [1] Introduction =
9
10	Google Android XWiki Connector was the first step towards XWiki mobility through android platform. Here the Idea is to improve it as a XWiki Android mobile Platform where developers can build their own applications on top of it.
11
12	This is the continuation of the project: [[url:http://extensions.xwiki.org/xwiki/bin/view/Extension/Google+Android+Client]]
13
14	= [2] Project architecture =
15
16	= (% class="xoffice1" %)[[image:image001.png\|\|height="700" width="900"]](%%) =
17
18
19
20	= =
21
22	= =
23
24	\\
25
26	= [3] Introduction to architectural components. =
27
28	== Xwiki RESTful Connector ==
29
30	(% class="xoffice2" %)
31	=== a) ReST Connector ===
32
33	(% class="MsoNormal xoffice3" %)
34	This layer is concerned with communicating with the XWiki server instance via REST.
35	For further detail on the low level API provided by this component see http://extensions.xwiki.org/xwiki/bin/view/Extension/Google+Android+Client
36
37
38
39	(((
40	(% cellpadding="0" cellspacing="0" style="text-align:left" %)
41	\|\\
42	\|\|[[image:image002.png\|\|height="176" width="563"]]
43	)))
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64	Above module abstract the XWiki Restful API documented here [[http:~~/~~/platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI>>url:http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI]] .
65
66
67
68	(% class="xoffice6" %)
69	=== b) ReST models ===
70
71	(% class="MsoNormal xoffice7" %)
72	Contains models representing Xwiki RESTful resources such as Page element, Object element and etc. XML RESTful communication is supported by xwiki-rest-model-simple-xml. ( [[http:~~/~~/extensions.xwiki.org/xwiki/bin/view/Extension/Google+Android+Client>>url:http://extensions.xwiki.org/xwiki/bin/view/Extension/Google+Android+Client]] )
73
74	(% class="xoffice8" %)
75	=== C ) RAL ===
76
77	(% class="MsoNoSpacing xoffice9" %)
78	Rest Access Layer. This is a simplified model for accessing XWiki RESTful API. Strips down all the fine grained calls of XWiki RESTful API to simple CRUD (Create, Retreive, Update, Delete) operations. Making the programming model much more simple. The RAL module supports CRUD operations only for the main first class entities which are Document, Space, Wiki.
79
80	(% class="xoffice10" %)
81	=== (% class="xoffice11" %)d)(%%) Transformation ===
82
83	(% class="MsoNoSpacing xoffice12" %)
84	This component is used for transforming the Xwiki Domain Model into underlying Xwiki Rest Model for communication with the server.
85
86
87
88	== (% class="xoffice14" %)Domain Model(%%) ==
89
90	(% class="xoffice15" %)
91	=== a) Xwiki Domain Model ===
92
93	(% class="MsoNormal xoffice16" %)
94	This is a representation of the XWiki Domain model. It represents Domain objects for Wiki, Spaces, Document, and Attachments etc.Mobile version of XWiki module "model". Also represents the Xwik Class, Object, Properties model. Refer [[(% class="xoffice17" %)http:~~/~~/platform.xwiki.org/xwiki/bin/view/DevGuide/DataModel>>url:http://platform.xwiki.org/xwiki/bin/view/DevGuide/DataModel]](%%) for Xwiki data model.
95
96	(% class="MsoNormal xoffice18" %)
97	These model entities can directly be transformed to android RESTful model and thus be used to manipulate the state of the server. Ex: a Document object in the XA(XWiki Android) is same as that in XE. So a Document object that is created in the client application can be directly send to the server through the RAL so that it will be created in the server as well.
98
99	(% class="xoffice19" %)
100	=== (% class="xoffice20" %)b) (% class="xoffice21" %)Xwiki Android Entities(%%) ===
101
102	This contains model entities wich are not directly adopted from Xwiki Enterprise Domain mode. Represents entities such as User, AuditEntry etc.
103
104	These entities do not have a direct mapping with the Domain model of the server. These entities are there to represent XWiki Android specific data model.
105
106	== File Store ==
107
108	(% class="MsoNormal xoffice22" %)
109	The File Store is the module that allows persistence for XWiki Domain model objects. For example you can directly save a Xwiki Document object in to the android device through the file store apis.
110
111	(% class="MsoNormal xoffice23" %)
112	Contains APIs for saving, loading, deleting, listing all Xwiki Domain Entities in the device. This module is designed with Data Access Object Pattern offering objects named as Fao(File Access Objects). When a Xwiki model object like document is in need to be persisted we can use a Fao to save it to the device. The file store implementation saved the entity as a file in the device and keeps a lightweight reference to the saved entity in the SQLite database .
113
114	== DAL ==
115
116	(% class="MsoNormal xoffice24" %)
117	The Data Access Layer provides functionality to persist XWiki Android Entities in to the SQLite Database. The API is very simple to use as this layer provides simple Object to Relational mapping through Data Access Objects.
118
119
120
121	== Base Services ==
122
123	(% class="MsoNormal xoffice25" %)
124	These are simply business facades that simplify the usage of underlying APIs such as RAL, FAL, DAL.
125
126	(% class="MsoNormal xoffice26" %)
127	The base services provide service functionality as follows.
128
129	(% class="MsoNormal xoffice27" %)
130	a) Xwiki Model Remote Services,
131
132	(% class="MsoNormal xoffice28" %)
133	Ex: Create, Retreive ,Querry, Update and Delete services for Documents.
134
135	(% class="MsoNormal xoffice29" %)
136	b) Xwiki Model Local Services
137
138	(% class="MsoNormal xoffice30" %)
139	Ex: Save, Load, List saved documents and Delete services for Documents.
140
141	(% class="MsoNormal xoffice31" %)
142	c) Xwiki Common Services
143
144	(% class="MsoNormal xoffice32" %)
145	Ex: Login service .
146
147
148
149	== App Specific Services ==
150
151
152
153	(% class="MsoNormal xoffice33" %)
154	These services use the Base services. But are specific for each application. For example if you are creating a blog application there are blog application specific features that need to be implemented. The Android activities can directly use the Base services but implementing them as a separate layer will lead to a cleaner design.
155
156
157
158	== Xwiki Application Context ==
159
160	(% class="MsoNormal xoffice35" %)
161	This is one of the core parts of the architecture. The XWiki Application Context is used for simple IoC. The control of constructing EntityManagers(DAL layer), FileStoreManagers( FAL layer) and other major components are given to the Application Context.
162
163
164
165	== Sync ==
166
167	(% class="MsoNormal xoffice37" %)
168	Provides APIs for automatically syncing XWiki Domain Model state on the device with that in the remote Server.
169
170	(% class="MsoNormal xoffice38" %)
171	For example this API can be used to automatically sync a Document when the user could not upload it to the server due to connectivity issues.
172
173
174
175	== Security and Audit ==
176
177	(% class="MsoNormal xoffice40" %)
178	Packs functionality for encrypting and auditing user activities.
179
180
181
182
183
184
185
186	= [4] API Usage =
187
188	== 1) How to create a Document. ==
189
190
191
192
193
194	(% class="xoffice44" %)import(%%) (% class="xoffice45" %)org.xwiki.android.blog.xobj.XBlogPost;
195
196	(% class="MsoNormal xoffice46" %)
197	(% class="xoffice47" %)import(%%) (% class="xoffice48" %)org.xwiki.android.ral.RaoException;
198
199	(% class="MsoNormal xoffice49" %)
200	(% class="xoffice50" %)import(%%) (% class="xoffice51" %)org.xwiki.android.xmodel.entity.Document;
201
202	(% class="MsoNormal xoffice52" %)
203	(% class="xoffice53" %)import(%%) (% class="xoffice54" %)org.xwiki.android.xmodel.entity.Document;
204
205	(% class="MsoNormal xoffice55" %)
206	(% class="xoffice56" %)import(%%) (% class="xoffice57" %)org.xwiki.android.xmodel.svc.DocumentRemoteSvcCallbacks;
207
208	(% class="MsoNormal xoffice58" %)
209	(% class="xoffice59" %)import(%%) (% class="xoffice60" %)org.xwiki.android.xmodel.svc.DocumentRemoteSvcs;
210
211	(% class="MsoNormal xoffice61" %)
212	(% class="xoffice62" %)import(%%) (% class="xoffice63" %)org.xwiki.android.xmodel.svc.DocumentSvcImpl;
213
214	...
215
216
217
218	(% class="MsoNormal xoffice64" %)
219	(% class="xoffice65" %)Document mydoc=(%%) (% class="xoffice66" %)new(%%) (% class="xoffice67" %)Document((%%) (% class="xoffice68" %)"wikiName"(%%) (% class="xoffice69" %),(%%) (% class="xoffice70" %)"spaceName"(%%) (% class="xoffice71" %),(%%) (% class="xoffice72" %)"pageName"(%%) (% class="xoffice73" %));(%%) (% class="xoffice74" %)~/~/create empty document
220
221	(% class="xoffice76" %)~/~/lets make a Blog.BlogPostClass object to put into __mydoc__ .
222
223	(% class="xoffice78" %)~/~/ in XA all model objects,classes, properties are prefixed with X.
224
225	(% class="xoffice79" %)XBlogPost blgpstObj=(%%) (% class="xoffice80" %)new(%%) (% class="xoffice81" %)XBlogPost();(%%) (% class="xoffice82" %)~/~/ Blog.BlogPostClass is know as ...blog.xobj.XBlogPost. Here we have removed
226
227	(% class="xoffice84" %)~/~/ the suffix Class and added a prefix X.
228
229
230
231	(% class="xoffice87" %)~/~/lets edit some properties of the XBlogPost object
232
233	(% class="xoffice88" %)blgpstObj.setContent((%%) (% class="xoffice89" %)"This blog post is created with Xwiki Android"(%%) (% class="xoffice90" %));
234
235	(% class="xoffice91" %)mydoc.addObject(blgpstObj);
236
237
238
239	(% class="xoffice93" %)DocumentRemoteSvcs docsvc=(%%) (% class="xoffice94" %)new(%%) (% class="xoffice95" %)DocumentSvcImpl();(%%) (% class="xoffice96" %)~/~/ the current implementation for DocumentRemoteSvcs is this.
240
241
242
243	(% class="xoffice99" %)~/~/ __docsvc__ can be used to __creat__ the document on the server. The service uses a __seperate__ thread to do all the work.
244
245	(% class="xoffice101" %)~/~/The results are given through a callback.
246
247
248
249	(% class="xoffice103" %)DocumentRemoteSvcCallbacks clbk=(%%) (% class="xoffice104" %)new(%%) (% class="xoffice105" %)DocumentRemoteSvcCallbacks()
250
251	(% class="xoffice106" %){
252
253	(% class="xoffice108" %)@Override
254
255	(% class="xoffice110" %)public(%%) (% class="xoffice111" %)void(%%) (% class="xoffice112" %)onCreated(Document res,(%%) (% class="xoffice113" %)boolean(%%) (% class="xoffice114" %)success, RaoException ex)
256
257	(% class="xoffice115" %){
258
259	(% class="xoffice117" %)if(%%) (% class="xoffice118" %)(success){
260
261	(% class="xoffice120" %)~/~/ update __ui__ here. You can notify the user that the doc was created in the server.
262
263	(% class="xoffice121" %)}(%%) (% class="xoffice122" %)else(%%) (% class="xoffice123" %){
264
265	(% class="xoffice125" %)~/~/you can check what the exception is and try to __rectify__ .
266
267	(% class="xoffice127" %)~/~/Most probably this same document is already existing in the server. So you should delete
268
269	(% class="xoffice129" %)~/~/the already existing one and recreate. Or you can do a simple update by docsvc.update( __mydoc__ , __clbk__ );
270
271	(% class="xoffice130" %)}
272
273	(% class="xoffice131" %)}
274
275	(% class="xoffice132" %)};
276
277	(% class="xoffice133" %)docsvc.create(mydoc,clbk);(%%) (% class="xoffice134" %)~/~/ __ok__ the __docsvc__ does all the work of creating a page for the document and then adding
278
279	(% class="xoffice136" %)~/~/ all those objects,tags,comments and attachments in the document.
280
281
282
283
284
285	(% class="MsoNormal xoffice139" %)
286	...
287
288
289
290	== 2) Advanced manipulation of XObjects. ==
291
292
293
294	(% class="MsoNormal xoffice141" %)
295	(% class="xoffice142" %)import(%%) (% class="xoffice143" %)__org.xwiki.android.blog.xobj.XBlogPost__ ;
296
297	(% class="MsoNormal xoffice144" %)
298	(% class="xoffice145" %)import(%%) (% class="xoffice146" %)org.xwiki.android.xmodel.entity.Document;
299
300	(% class="MsoNormal xoffice147" %)
301	(% class="xoffice148" %)import(%%) (% class="xoffice149" %)__org.xwiki.android.xmodel.xobjects.XBooleanProperty__ ;
302
303
304
305	(% class="MsoNormal xoffice151" %)
306	(% class="xoffice152" %)...
307
308
309
310	(% class="MsoNormal xoffice153" %)
311	(% class="xoffice154" %)Document __mydoc__ =(%%) (% class="xoffice155" %)new(%%) (% class="xoffice156" %)Document((%%) (% class="xoffice157" %)"wikiName"(%%) (% class="xoffice158" %),(%%) (% class="xoffice159" %)"spaceName"(%%) (% class="xoffice160" %),(%%) (% class="xoffice161" %)"pageName"(%%) (% class="xoffice162" %));(%%) (% class="xoffice163" %)~/~/create empty document
312
313	(% class="MsoNormal xoffice164" %)
314	(% class="xoffice165" %)XBlogPost blgpstObj=(%%) (% class="xoffice166" %)new(%%) (% class="xoffice167" %)XBlogPost();
315
316	(% class="MsoNormal xoffice168" %)
317	(% class="xoffice169" %)blgpstObj.setHidden((%%) (% class="xoffice170" %)true(%%) (% class="xoffice171" %));(%%) (% class="xoffice172" %)~/~/simple way to edit the value of "hidden" property of XBlogPost.
318
319
320
321	(% class="MsoNormal xoffice175" %)
322	(% class="xoffice177" %)~/~/say, now we want to do some advanced stuff with that property.
323
324	(% class="MsoNormal xoffice178" %)
325	(% class="xoffice179" %)XBooleanProperty hiddenP= blgpstObj.getpHidden();(%%) (% class="xoffice180" %)~/~/ use __getp__ , __setp__ methods to get the property.
326
327	(% class="MsoNormal xoffice181" %)
328	(% class="xoffice183" %)~/~/lets change hidden again.
329
330	(% class="MsoNormal xoffice184" %)
331	(% class="xoffice185" %)hiddenP.setValue((%%) (% class="xoffice186" %)false(%%) (% class="xoffice187" %));
332
333	(% class="MsoNormal xoffice188" %)
334	(% class="xoffice190" %)~/~/change an attribute of the property.
335
336	(% class="MsoNormal xoffice191" %)
337	(% class="xoffice192" %)hiddenP.setPrettyName((%%) (% class="xoffice193" %)"Hidden pretty name"(%%) (% class="xoffice194" %));
338
339
340
341	(% class="MsoNormal xoffice197" %)
342	(% class="xoffice199" %)~/~/Since a reference is passed, you do not have to blgpstObj.setpHidden(hiddenP) to commit the effects.
343
344
345
346	(% class="MsoNormal xoffice201" %)
347	(% class="xoffice202" %)....
348
349	== 3) Save a Document ==
350
351	(% class="MsoNormal xoffice203" %)
352	(% class="xoffice204" %)import(%%) (% class="xoffice205" %)org.xwiki.android.xmodel.entity.Document;
353
354	(% class="MsoNormal xoffice206" %)
355	(% class="xoffice207" %)import(%%) (% class="xoffice208" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcs;
356
357	(% class="MsoNormal xoffice209" %)
358	(% class="xoffice210" %)import(%%) (% class="xoffice211" %)org.xwiki.android.xmodel.svc.DocumentSvcImpl;
359
360
361
362	(% class="MsoNormal xoffice213" %)
363	(% class="xoffice214" %)....
364
365
366
367	(% class="MsoNormal xoffice215" %)
368	(% class="xoffice216" %)Document mydoc=(%%) (% class="xoffice217" %)new(%%) (% class="xoffice218" %)Document((%%) (% class="xoffice219" %)"wikiName"(%%) (% class="xoffice220" %),(%%) (% class="xoffice221" %)"spaceName"(%%) (% class="xoffice222" %),(%%) (% class="xoffice223" %)"pageName"(%%) (% class="xoffice224" %));(%%) (% class="xoffice225" %)~/~/create empty document
369
370	(% class="xoffice227" %)~/~/ ... edit __mydoc__
371
372
373
374	(% class="xoffice230" %)~/~/lets save it!
375
376
377
378	(% class="xoffice232" %)DocumentLocalSvcs docsvcl=(%%) (% class="xoffice233" %)new(%%) (% class="xoffice234" %)DocumentSvcImpl();
379
380
381
382	(% class="xoffice236" %)docsvcl.save(mydoc,(%%) (% class="xoffice237" %)"My tag to identify this easily"(%%) (% class="xoffice238" %),(%%) (% class="xoffice239" %)null(%%) (% class="xoffice240" %));(%%) (% class="xoffice241" %)~/~/docsvcl.save(doc, tag, __clbk__ ). we pass null for __clbk__
383
384	(% class="xoffice243" %)~/~/ since we do not want to know __wether__ the doc was __sucessfully__
385
386	(% class="xoffice245" %)~/~/ saved or not.
387
388
389
390
391
392	(% class="MsoNormal xoffice248" %)
393	(% class="xoffice249" %)....
394
395	== 4] Save Document and get notified of the save completion. ==
396
397
398
399	(% class="MsoNormal xoffice250" %)
400	(% class="xoffice251" %)import(%%) (% class="xoffice252" %)java.io.File;
401
402
403
404	(% class="MsoNormal xoffice254" %)
405	(% class="xoffice255" %)import(%%) (% class="xoffice256" %)org.xwiki.android.xmodel.entity.Document;
406
407	(% class="MsoNormal xoffice257" %)
408	(% class="xoffice258" %)import(%%) (% class="xoffice259" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcCallbacks;
409
410	(% class="MsoNormal xoffice260" %)
411	(% class="xoffice261" %)import(%%) (% class="xoffice262" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcs;
412
413	(% class="MsoNormal xoffice263" %)
414	(% class="xoffice264" %)import(%%) (% class="xoffice265" %)org.xwiki.android.xmodel.svc.DocumentSvcImpl;
415
416
417
418	...
419
420
421
422	(% class="MsoNormal xoffice266" %)
423	(% class="xoffice267" %)Document mydoc=(%%) (% class="xoffice268" %)new(%%) (% class="xoffice269" %)Document((%%) (% class="xoffice270" %)"wikiName"(%%) (% class="xoffice271" %),(%%) (% class="xoffice272" %)"spaceName"(%%) (% class="xoffice273" %),(%%) (% class="xoffice274" %)"pageName"(%%) (% class="xoffice275" %));(%%) (% class="xoffice276" %)~/~/create empty document
424
425	(% class="xoffice278" %)~/~/ ... edit __mydoc__
426
427
428
429
430
431	(% class="xoffice281" %)DocumentLocalSvcs docsvcl=(%%) (% class="xoffice282" %)new(%%) (% class="xoffice283" %)DocumentSvcImpl();
432
433	(% class="xoffice284" %)DocumentLocalSvcCallbacks __clbk__ =(%%) (% class="xoffice285" %)new(%%) (% class="xoffice286" %)DocumentLocalSvcCallbacks()
434
435	(% class="xoffice287" %){
436
437	(% class="xoffice289" %)@Override
438
439	(% class="xoffice291" %)public(%%) (% class="xoffice292" %)void(%%) (% class="xoffice293" %)onSaveComplete(File savedto)
440
441	(% class="xoffice294" %){
442
443	(% class="xoffice296" %)if(%%) (% class="xoffice297" %)(savedto!=(%%) (% class="xoffice298" %)null(%%) (% class="xoffice299" %)){
444
445	(% class="xoffice301" %)~/~/success. Edit UI to notify user here.
446
447	(% class="xoffice302" %)}(%%) (% class="xoffice303" %)else(%%) (% class="xoffice304" %){
448
449	(% class="xoffice306" %)~/~/oops problem. May be the device storage is full.
450
451	(% class="xoffice307" %)}
452
453
454
455	(% class="xoffice309" %)}
456
457	(% class="xoffice310" %)};
458
459	(% class="xoffice311" %)docsvcl.save(mydoc,(%%) (% class="xoffice312" %)"My tag to identify this easily"(%%) (% class="xoffice313" %),(%%) (% class="xoffice314" %)null(%%) (% class="xoffice315" %));
460
461
462
463	...
464
465	== ==
466
467	== 5] List and Load documents in File Store ==
468
469
470
471	(% class="xoffice316" %)import(%%) (% class="xoffice317" %)java.util.List;
472
473	(% class="MsoNormal xoffice318" %)
474	(% class="xoffice319" %)import(%%) (% class="xoffice320" %)java.util.Map;
475
476
477
478	(% class="MsoNormal xoffice322" %)
479	(% class="xoffice323" %)import(%%) (% class="xoffice324" %)org.xwiki.android.fileStore.FSDocumentReference;
480
481	(% class="MsoNormal xoffice325" %)
482	(% class="xoffice326" %)import(%%) (% class="xoffice327" %)org.xwiki.android.xmodel.entity.Document;
483
484	(% class="MsoNormal xoffice328" %)
485	(% class="xoffice329" %)import(%%) (% class="xoffice330" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcCallbacks;
486
487	(% class="MsoNormal xoffice331" %)
488	(% class="xoffice332" %)import(%%) (% class="xoffice333" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcs;
489
490	(% class="MsoNormal xoffice334" %)
491	(% class="xoffice335" %)import(%%) (% class="xoffice336" %)org.xwiki.android.xmodel.svc.DocumentSvcImpl;
492
493
494
495	(% class="MsoNormal xoffice338" %)
496	(% class="xoffice339" %)import(%%) (% class="xoffice340" %)android.app.Activity;
497
498
499
500	(% class="MsoNormal xoffice342" %)

This page is for future development and ideas about XWiki Android tools.

4

5

See current state at [[extensions:Extension.Google Android Client]].

(((

= [1] Introduction =

Google Android XWiki Connector was the first step towards XWiki mobility through android platform. Here the Idea is to improve it as a XWiki Android mobile Platform where developers can build their own applications on top of it.

11

12

This is the continuation of the project: [[url:http://extensions.xwiki.org/xwiki/bin/view/Extension/Google+Android+Client]]

13

14

= [2] Project architecture =

15

16

= (% class="xoffice1" %)[[image:image001.png||height="700" width="900"]](%%) =

= =

= =

\\

= [3] Introduction to architectural components. =

27

28

== Xwiki RESTful Connector ==

29

30

(% class="xoffice2" %)

31

=== a) ReST Connector ===

32

33

(% class="MsoNormal xoffice3" %)

34

This layer is concerned with communicating with the XWiki server instance via REST.

35

For further detail on the low level API provided by this component see http://extensions.xwiki.org/xwiki/bin/view/Extension/Google+Android+Client

(((

(% cellpadding="0" cellspacing="0" style="text-align:left" %)

41

|\\

42

||[[image:image002.png||height="176" width="563"]]

)))

Above module abstract the XWiki Restful API documented here [[http:~~/~~/platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI>>url:http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI]] .

(% class="xoffice6" %)

69

=== b) ReST models ===

70

71

(% class="MsoNormal xoffice7" %)

72

Contains models representing Xwiki RESTful resources such as Page element, Object element and etc. XML RESTful communication is supported by xwiki-rest-model-simple-xml. ( [[http:~~/~~/extensions.xwiki.org/xwiki/bin/view/Extension/Google+Android+Client>>url:http://extensions.xwiki.org/xwiki/bin/view/Extension/Google+Android+Client]] )

73

74

(% class="xoffice8" %)

75

=== C ) RAL ===

76

77

(% class="MsoNoSpacing xoffice9" %)

78

Rest Access Layer. This is a simplified model for accessing XWiki RESTful API. Strips down all the fine grained calls of XWiki RESTful API to simple CRUD (Create, Retreive, Update, Delete) operations. Making the programming model much more simple. The RAL module supports CRUD operations only for the main first class entities which are Document, Space, Wiki.

79

80

(% class="xoffice10" %)

81

=== (% class="xoffice11" %)d)(%%) Transformation ===

82

83

(% class="MsoNoSpacing xoffice12" %)

84

This component is used for transforming the Xwiki Domain Model into underlying Xwiki Rest Model for communication with the server.

== (% class="xoffice14" %)**Domain Model**(%%) ==

89

90

(% class="xoffice15" %)

91

=== a) Xwiki Domain Model ===

92

93

(% class="MsoNormal xoffice16" %)

94

This is a representation of the XWiki Domain model. It represents Domain objects for Wiki, Spaces, Document, and Attachments etc.Mobile version of XWiki module "model". Also represents the Xwik Class, Object, Properties model. Refer [[(% class="xoffice17" %)http:~~/~~/platform.xwiki.org/xwiki/bin/view/DevGuide/DataModel>>url:http://platform.xwiki.org/xwiki/bin/view/DevGuide/DataModel]](%%) for Xwiki data model.

95

96

(% class="MsoNormal xoffice18" %)

97

These model entities can directly be transformed to android RESTful model and thus be used to manipulate the state of the server. Ex: a Document object in the XA(XWiki Android) is same as that in XE. So a Document object that is created in the client application can be directly send to the server through the RAL so that it will be created in the server as well.

98

99

(% class="xoffice19" %)

100

=== (% class="xoffice20" %)**b) **(% class="xoffice21" %)**Xwiki Android Entities**(%%) ===

101

102

**This contains model entities wich are not directly adopted from Xwiki Enterprise Domain mode. Represents entities such as User, AuditEntry etc.**

103

104

These entities do not have a direct mapping with the Domain model of the server. These entities are there to represent XWiki Android specific data model.

== File Store ==

(% class="MsoNormal xoffice22" %)

109

The File Store is the module that allows persistence for XWiki Domain model objects. For example you can directly save a Xwiki Document object in to the android device through the file store apis.

110

111

(% class="MsoNormal xoffice23" %)

112

Contains APIs for saving, loading, deleting, listing all Xwiki Domain Entities in the device. This module is designed with Data Access Object Pattern offering objects named as Fao(File Access Objects). When a Xwiki model object like document is in need to be persisted we can use a Fao to save it to the device. The file store implementation saved the entity as a file in the device and keeps a lightweight reference to the saved entity in the SQLite database **.**

== DAL ==

(% class="MsoNormal xoffice24" %)

117

The Data Access Layer provides functionality to persist XWiki Android Entities in to the SQLite Database. The API is very simple to use as this layer provides simple Object to Relational mapping through Data Access Objects.

== Base Services ==

(% class="MsoNormal xoffice25" %)

124

These are simply business facades that simplify the usage of underlying APIs such as RAL, FAL, DAL.

125

126

(% class="MsoNormal xoffice26" %)

127

The base services provide service functionality as follows.

128

129

(% class="MsoNormal xoffice27" %)

130

a) Xwiki Model Remote Services,

131

132

(% class="MsoNormal xoffice28" %)

133

Ex: Create, Retreive ,Querry, Update and Delete services for Documents.

134

135

(% class="MsoNormal xoffice29" %)

136

b) Xwiki Model Local Services

137

138

(% class="MsoNormal xoffice30" %)

139

Ex: Save, Load, List saved documents and Delete services for Documents.

140

141

(% class="MsoNormal xoffice31" %)

142

c) Xwiki Common Services

143

144

(% class="MsoNormal xoffice32" %)

145

Ex: Login service **.**

== App Specific Services ==

(% class="MsoNormal xoffice33" %)

154

These services use the Base services. But are specific for each application. For example if you are creating a blog application there are blog application specific features that need to be implemented. The Android activities can directly use the Base services but implementing them as a separate layer will lead to a cleaner design.

== Xwiki Application Context ==

159

160

(% class="MsoNormal xoffice35" %)

161

This is one of the core parts of the architecture. The XWiki Application Context is used for simple IoC. The control of constructing EntityManagers(DAL layer), FileStoreManagers( FAL layer) and other major components are given to the Application Context.

== Sync ==

(% class="MsoNormal xoffice37" %)

168

Provides APIs for automatically syncing XWiki Domain Model state on the device with that in the remote Server.

169

170

(% class="MsoNormal xoffice38" %)

171

For example this API can be used to automatically sync a Document when the user could not upload it to the server due to connectivity issues.

== Security and Audit ==

176

177

(% class="MsoNormal xoffice40" %)

178

Packs functionality for encrypting and auditing user activities.

= [4] API Usage =

== 1) How to create a Document. ==

(% class="xoffice44" %)**import**(%%)** **(% class="xoffice45" %)org.xwiki.android.blog.xobj.XBlogPost;

195

196

(% class="MsoNormal xoffice46" %)

197

(% class="xoffice47" %)**import**(%%)** **(% class="xoffice48" %)org.xwiki.android.ral.RaoException;

198

199

(% class="MsoNormal xoffice49" %)

200

(% class="xoffice50" %)**import**(%%)** **(% class="xoffice51" %)org.xwiki.android.xmodel.entity.Document;

201

202

(% class="MsoNormal xoffice52" %)

203

(% class="xoffice53" %)**import**(%%)** **(% class="xoffice54" %)org.xwiki.android.xmodel.entity.Document;

204

205

(% class="MsoNormal xoffice55" %)

206

(% class="xoffice56" %)**import**(%%)** **(% class="xoffice57" %)org.xwiki.android.xmodel.svc.DocumentRemoteSvcCallbacks;

207

208

(% class="MsoNormal xoffice58" %)

209

(% class="xoffice59" %)**import**(%%)** **(% class="xoffice60" %)org.xwiki.android.xmodel.svc.DocumentRemoteSvcs;

210

211

(% class="MsoNormal xoffice61" %)

212

(% class="xoffice62" %)**import**(%%)** **(% class="xoffice63" %)org.xwiki.android.xmodel.svc.DocumentSvcImpl;

**...**

(% class="MsoNormal xoffice64" %)

219

(% class="xoffice65" %)Document mydoc=(%%) (% class="xoffice66" %)**new**(%%)** **(% class="xoffice67" %)Document((%%) (% class="xoffice68" %)"wikiName"(%%) (% class="xoffice69" %),(%%) (% class="xoffice70" %)"spaceName"(%%) (% class="xoffice71" %),(%%) (% class="xoffice72" %)"pageName"(%%) (% class="xoffice73" %));(%%) (% class="xoffice74" %)~/~/create empty document

220

221

(% class="xoffice76" %)~/~/lets make a Blog.BlogPostClass object to put into __mydoc__ .

222

223

(% class="xoffice78" %)~/~/ in XA all model objects,classes, properties are prefixed with X.

224

225

(% class="xoffice79" %)XBlogPost blgpstObj=(%%) (% class="xoffice80" %)**new**(%%)** **(% class="xoffice81" %)XBlogPost();(%%) (% class="xoffice82" %)~/~/ Blog.BlogPostClass is know as ...blog.xobj.XBlogPost. Here we have removed

226

227

(% class="xoffice84" %)~/~/ the suffix Class and added a prefix X.

(% class="xoffice87" %)~/~/lets edit some properties of the XBlogPost object

232

233

(% class="xoffice88" %)blgpstObj.setContent((%%) (% class="xoffice89" %)"This blog post is created with Xwiki Android"(%%) (% class="xoffice90" %));

234

235

(% class="xoffice91" %)mydoc.addObject(blgpstObj);

(% class="xoffice93" %)DocumentRemoteSvcs docsvc=(%%) (% class="xoffice94" %)**new**(%%)** **(% class="xoffice95" %)DocumentSvcImpl();(%%) (% class="xoffice96" %)~/~/ the current implementation for DocumentRemoteSvcs is this.

(% class="xoffice99" %)~/~/ __docsvc__ can be used to __creat__ the document on the server. The service uses a __seperate__ thread to do all the work.

244

245

(% class="xoffice101" %)~/~/The results are given through a callback.

(% class="xoffice103" %)DocumentRemoteSvcCallbacks clbk=(%%) (% class="xoffice104" %)**new**(%%)** **(% class="xoffice105" %)DocumentRemoteSvcCallbacks()

250

251

(% class="xoffice106" %){

252

253

(% class="xoffice108" %)@Override

254

255

(% class="xoffice110" %)**public**(%%)** (% class="xoffice111" %)void(%%) **(% class="xoffice112" %)onCreated(Document res,(%%) (% class="xoffice113" %)**boolean**(%%)** **(% class="xoffice114" %)success, RaoException ex)

256

257

(% class="xoffice115" %){

258

259

(% class="xoffice117" %)**if**(%%)** **(% class="xoffice118" %)(success){

260

261

(% class="xoffice120" %)~/~/ update __ui__ here. You can notify the user that the doc was created in the server.

262

263

(% class="xoffice121" %)}(%%) (% class="xoffice122" %)**else**(%%)** **(% class="xoffice123" %){

264

265

(% class="xoffice125" %)~/~/you can check what the exception is and try to __rectify__ .

266

267

(% class="xoffice127" %)~/~/Most probably this same document is already existing in the server. So you should delete

268

269

(% class="xoffice129" %)~/~/the already existing one and recreate. Or you can do a simple update by docsvc.update( __mydoc__ , __clbk__ );

270

271

(% class="xoffice130" %)}

272

273

(% class="xoffice131" %)}

274

275

(% class="xoffice132" %)};

276

277

(% class="xoffice133" %)docsvc.create(mydoc,clbk);(%%) (% class="xoffice134" %)~/~/ __ok__ the __docsvc__ does all the work of creating a page for the document and then adding

278

279

(% class="xoffice136" %)~/~/ all those objects,tags,comments and attachments in the document.

(% class="MsoNormal xoffice139" %)

**...**

== 2) Advanced manipulation of XObjects. ==

(% class="MsoNormal xoffice141" %)

295

(% class="xoffice142" %)**import**(%%)** **(% class="xoffice143" %)__org.xwiki.android.blog.xobj.XBlogPost__ ;

296

297

(% class="MsoNormal xoffice144" %)

298

(% class="xoffice145" %)**import**(%%)** **(% class="xoffice146" %)org.xwiki.android.xmodel.entity.Document;

299

300

(% class="MsoNormal xoffice147" %)

301

(% class="xoffice148" %)**import**(%%)** **(% class="xoffice149" %)__org.xwiki.android.xmodel.xobjects.XBooleanProperty__ ;

(% class="MsoNormal xoffice151" %)

306

(% class="xoffice152" %)...

(% class="MsoNormal xoffice153" %)

311

(% class="xoffice154" %)Document __mydoc__ =(%%) (% class="xoffice155" %)**new**(%%)** **(% class="xoffice156" %)Document((%%) (% class="xoffice157" %)"wikiName"(%%) (% class="xoffice158" %),(%%) (% class="xoffice159" %)"spaceName"(%%) (% class="xoffice160" %),(%%) (% class="xoffice161" %)"pageName"(%%) (% class="xoffice162" %));(%%) (% class="xoffice163" %)~/~/create empty document

312

313

(% class="MsoNormal xoffice164" %)

314

(% class="xoffice165" %)XBlogPost blgpstObj=(%%) (% class="xoffice166" %)**new**(%%)** **(% class="xoffice167" %)XBlogPost();

315

316

(% class="MsoNormal xoffice168" %)

317

(% class="xoffice169" %)blgpstObj.setHidden((%%) (% class="xoffice170" %)**true**(%%)** **(% class="xoffice171" %));(%%) (% class="xoffice172" %)~/~/simple way to edit the value of "hidden" property of XBlogPost.

(% class="MsoNormal xoffice175" %)

322

(% class="xoffice177" %)~/~/say, now we want to do some advanced stuff with that property.

323

324

(% class="MsoNormal xoffice178" %)

325

(% class="xoffice179" %)XBooleanProperty hiddenP= blgpstObj.getpHidden();(%%) (% class="xoffice180" %)~/~/ use __getp__ , __setp__ methods to get the property.

326

327

(% class="MsoNormal xoffice181" %)

328

(% class="xoffice183" %)~/~/lets change hidden again.

329

330

(% class="MsoNormal xoffice184" %)

331

(% class="xoffice185" %)hiddenP.setValue((%%) (% class="xoffice186" %)**false**(%%)** **(% class="xoffice187" %));

332

333

(% class="MsoNormal xoffice188" %)

334

(% class="xoffice190" %)~/~/change an attribute of the property.

335

336

(% class="MsoNormal xoffice191" %)

337

(% class="xoffice192" %)hiddenP.setPrettyName((%%) (% class="xoffice193" %)"Hidden pretty name"(%%) (% class="xoffice194" %));

(% class="MsoNormal xoffice197" %)

342

(% class="xoffice199" %)~/~/Since a reference is passed, you do not have to blgpstObj.setpHidden(hiddenP) to commit the effects.

(% class="MsoNormal xoffice201" %)

347

(% class="xoffice202" %)....

348

349

== 3) Save a Document ==

350

351

(% class="MsoNormal xoffice203" %)

352

(% class="xoffice204" %)**import**(%%)** **(% class="xoffice205" %)org.xwiki.android.xmodel.entity.Document;

353

354

(% class="MsoNormal xoffice206" %)

355

(% class="xoffice207" %)**import**(%%)** **(% class="xoffice208" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcs;

356

357

(% class="MsoNormal xoffice209" %)

358

(% class="xoffice210" %)**import**(%%)** **(% class="xoffice211" %)org.xwiki.android.xmodel.svc.DocumentSvcImpl;

(% class="MsoNormal xoffice213" %)

363

(% class="xoffice214" %)....

(% class="MsoNormal xoffice215" %)

368

(% class="xoffice216" %)Document mydoc=(%%) (% class="xoffice217" %)**new**(%%)** **(% class="xoffice218" %)Document((%%) (% class="xoffice219" %)"wikiName"(%%) (% class="xoffice220" %),(%%) (% class="xoffice221" %)"spaceName"(%%) (% class="xoffice222" %),(%%) (% class="xoffice223" %)"pageName"(%%) (% class="xoffice224" %));(%%) (% class="xoffice225" %)~/~/create empty document

369

370

(% class="xoffice227" %)~/~/ ... edit __mydoc__

(% class="xoffice230" %)~/~/lets save it!

(% class="xoffice232" %)DocumentLocalSvcs docsvcl=(%%) (% class="xoffice233" %)**new**(%%)** **(% class="xoffice234" %)DocumentSvcImpl();

(% class="xoffice236" %)docsvcl.save(mydoc,(%%) (% class="xoffice237" %)"My tag to identify this easily"(%%) (% class="xoffice238" %),(%%) (% class="xoffice239" %)**null**(%%)** **(% class="xoffice240" %));(%%) (% class="xoffice241" %)~/~/docsvcl.save(doc, tag, __clbk__ ). we pass null for __clbk__

383

384

(% class="xoffice243" %)~/~/ since we do not want to know __wether__ the doc was __sucessfully__

385

386

(% class="xoffice245" %)~/~/ saved or not.

(% class="MsoNormal xoffice248" %)

393

(% class="xoffice249" %)....

394

395

== 4] Save Document and get notified of the save completion. ==

(% class="MsoNormal xoffice250" %)

400

(% class="xoffice251" %)**import**(%%)** **(% class="xoffice252" %)java.io.File;

(% class="MsoNormal xoffice254" %)

405

(% class="xoffice255" %)**import**(%%)** **(% class="xoffice256" %)org.xwiki.android.xmodel.entity.Document;

406

407

(% class="MsoNormal xoffice257" %)

408

(% class="xoffice258" %)**import**(%%)** **(% class="xoffice259" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcCallbacks;

409

410

(% class="MsoNormal xoffice260" %)

411

(% class="xoffice261" %)**import**(%%)** **(% class="xoffice262" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcs;

412

413

(% class="MsoNormal xoffice263" %)

414

(% class="xoffice264" %)**import**(%%)** **(% class="xoffice265" %)org.xwiki.android.xmodel.svc.DocumentSvcImpl;

...

(% class="MsoNormal xoffice266" %)

423

(% class="xoffice267" %)Document mydoc=(%%) (% class="xoffice268" %)**new**(%%)** **(% class="xoffice269" %)Document((%%) (% class="xoffice270" %)"wikiName"(%%) (% class="xoffice271" %),(%%) (% class="xoffice272" %)"spaceName"(%%) (% class="xoffice273" %),(%%) (% class="xoffice274" %)"pageName"(%%) (% class="xoffice275" %));(%%) (% class="xoffice276" %)~/~/create empty document

424

425

(% class="xoffice278" %)~/~/ ... edit __mydoc__

(% class="xoffice281" %)DocumentLocalSvcs docsvcl=(%%) (% class="xoffice282" %)**new**(%%)** **(% class="xoffice283" %)DocumentSvcImpl();

432

433

(% class="xoffice284" %)DocumentLocalSvcCallbacks __clbk__ =(%%) (% class="xoffice285" %)**new**(%%)** **(% class="xoffice286" %)DocumentLocalSvcCallbacks()

434

435

(% class="xoffice287" %){

436

437

(% class="xoffice289" %)@Override

438

439

(% class="xoffice291" %)**public**(%%)** (% class="xoffice292" %)void(%%) **(% class="xoffice293" %)onSaveComplete(File savedto)

440

441

(% class="xoffice294" %){

442

443

(% class="xoffice296" %)**if**(%%)** **(% class="xoffice297" %)(savedto!=(%%) (% class="xoffice298" %)**null**(%%)** **(% class="xoffice299" %)){

444

445

(% class="xoffice301" %)~/~/success. Edit UI to notify user here.

446

447

(% class="xoffice302" %)}(%%) (% class="xoffice303" %)**else**(%%)** **(% class="xoffice304" %){

448

449

(% class="xoffice306" %)~/~/oops problem. May be the device storage is full.

450

451

(% class="xoffice307" %)}

(% class="xoffice309" %)}

456

457

(% class="xoffice310" %)};

458

459

(% class="xoffice311" %)docsvcl.save(mydoc,(%%) (% class="xoffice312" %)"My tag to identify this easily"(%%) (% class="xoffice313" %),(%%) (% class="xoffice314" %)**null**(%%)** **(% class="xoffice315" %));

...

== ==

== 5] List and Load documents in File Store ==

(% class="xoffice316" %)**import**(%%)** **(% class="xoffice317" %)java.util.List;

472

473

(% class="MsoNormal xoffice318" %)

474

(% class="xoffice319" %)**import**(%%)** **(% class="xoffice320" %)java.util.Map;

(% class="MsoNormal xoffice322" %)

479

(% class="xoffice323" %)**import**(%%)** **(% class="xoffice324" %)org.xwiki.android.fileStore.FSDocumentReference;

480

481

(% class="MsoNormal xoffice325" %)

482

(% class="xoffice326" %)**import**(%%)** **(% class="xoffice327" %)org.xwiki.android.xmodel.entity.Document;

483

484

(% class="MsoNormal xoffice328" %)

485

(% class="xoffice329" %)**import**(%%)** **(% class="xoffice330" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcCallbacks;

486

487

(% class="MsoNormal xoffice331" %)

488

(% class="xoffice332" %)**import**(%%)** **(% class="xoffice333" %)org.xwiki.android.xmodel.svc.DocumentLocalSvcs;

489

490

(% class="MsoNormal xoffice334" %)

491

(% class="xoffice335" %)**import**(%%)** **(% class="xoffice336" %)org.xwiki.android.xmodel.svc.DocumentSvcImpl;

(% class="MsoNormal xoffice338" %)

496

(% class="xoffice339" %)**import**(%%)** **(% class="xoffice340" %)android.app.Activity;

(% class="MsoNormal xoffice342" %)

501

(% class="xoffice343" %)**public**(%%)** (% class="xoffice344" %)class(%%) **(% class="xoffice345" %)_05_ListAndLoadDocuments(%%) (% class="xoffice346" %)**extends**(%%)** **(% class="xoffice347" %)Activity

502

503

(% class="MsoNormal xoffice348" %)

504

(% class="xoffice349" %){

(% class="MsoNormal xoffice351" %)

509

(% class="xoffice352" %)FSDocumentReference(%%) (% class="xoffice353" %)loadMe(%%) (% class="xoffice354" %);

510

511

(% class="MsoNormal xoffice355" %)

512

(% class="xoffice356" %)DocumentLocalSvcs(%%) (% class="xoffice357" %)ds(%%) (% class="xoffice358" %);

(% class="MsoNormal xoffice360" %)

517

(% class="xoffice362" %)**protected**(%%)** (% class="xoffice363" %)void(%%) **(% class="xoffice364" %)__onCreate(android.os.Bundle savedInstanceState)__

518

519

(% class="MsoNormal xoffice365" %)

520

(% class="xoffice366" %){

(% class="MsoNormal xoffice368" %)

525

(% class="xoffice370" %)ds(%%) (% class="xoffice371" %)=(%%) (% class="xoffice372" %)**new**(%%)** **(% class="xoffice373" %)DocumentSvcImpl();

(% class="MsoNormal xoffice375" %)

530

(% class="xoffice376" %)DocumentLocalSvcCallbacks clbk1 =(%%) (% class="xoffice377" %)**new**(%%)** **(% class="xoffice378" %)DocumentLocalSvcCallbacks()

531

532

(% class="MsoNormal xoffice379" %)

533

(% class="xoffice380" %){

534

535

(% class="MsoNormal xoffice381" %)

536

(% class="xoffice383" %)@Override

537

538

(% class="MsoNormal xoffice384" %)

539

(% class="xoffice386" %)**public**(%%)** (% class="xoffice387" %)void(%%) **(% class="xoffice388" %)onListingComplete(List<FSDocumentReference> rslts, Map<String, Object> matchedby)

540

541

(% class="MsoNormal xoffice389" %)

542

(% class="xoffice390" %){

543

544

(% class="MsoNormal xoffice391" %)

545

(% class="xoffice393" %)~/~/ matched by will contain entry ("space", "MySpace")

546

547

(% class="MsoNormal xoffice394" %)

548

(% class="xoffice396" %)loadMe(%%) (% class="xoffice397" %)= rslts.get(0);

549

550

(% class="MsoNormal xoffice398" %)

551

(% class="xoffice399" %)loadThis((%%) (% class="xoffice400" %)loadMe(%%) (% class="xoffice401" %));

552

553

(% class="MsoNormal xoffice402" %)

554

(% class="xoffice403" %)}

555

556

(% class="MsoNormal xoffice404" %)

557

(% class="xoffice405" %)};

(% class="MsoNormal xoffice407" %)

562

(% class="xoffice409" %)ds(%%) (% class="xoffice410" %).listBySpace((%%) (% class="xoffice411" %)"MySpace"(%%) (% class="xoffice412" %), clbk1);

563

564

(% class="MsoNormal xoffice413" %)

565

(% class="xoffice415" %)~/~/ after the listing is complete you will be notified in the onListingComplete.

566

567

(% class="MsoNormal xoffice416" %)

568

(% class="xoffice417" %)}

(% class="MsoNormal xoffice419" %)

573

(% class="xoffice421" %)**private**(%%)** (% class="xoffice422" %)void(%%) **(% class="xoffice423" %)loadThis(FSDocumentReference ref)

574

575

(% class="MsoNormal xoffice424" %)

576

(% class="xoffice425" %){

577

578

(% class="MsoNormal xoffice426" %)

579

(% class="xoffice427" %)DocumentLocalSvcCallbacks clbk2 =(%%) (% class="xoffice428" %)**new**(%%)** **(% class="xoffice429" %)DocumentLocalSvcCallbacks()

580

581

(% class="MsoNormal xoffice430" %)

582

(% class="xoffice431" %){

583

584

(% class="MsoNormal xoffice432" %)

585

(% class="xoffice434" %)@Override

586

587