iphone app - clusterinfo.at

8/8/2019 iPhone App - clusterinfo.at

1/23

Seminar paper

iPhone App

clusterinfo.at

Stefan Almer, Bsc

[email protected]

Graz University of Technology

Institute for Information Systems and Computer Media

Adviser: Dipl.-Ing. Dr.techn. Josef Kolbitsch

Graz, September 2010


2/23

Abstract

Mobile devices such as Apples iPhone or various Google Android driven devices are

getting increasingly popular. With such devices and the possibility to access the internet

wirelessly it is possible to gain information everywhere on earth. For representing infor-

mation so called Apps (mobile applications) are used. Such applications are fast, easy to

use and often fit just one special purpose.

This paper deals with the implementation of the iPhone application clusterinfo.at. This

app represents the mobile userinterface to the existing web portal. To access the infor-

mation a REST based webservice API has been developed which provides various services

like searching. Every request is covered in a result set which only contains metadata about

the information found. The client needs to post a second request with the result set to getall records.

Keywords iphone, rest webservice, clusterinfo, human technology styria, xml

1


3/23

Statutory Declaration

I declare that I have authored this thesis independently, that I have not used other thanthe declared sources / resources, and that I have explicitly marked all material which has been

quoted either literally or by content from the used sources.

Date Signature

2


4/23

Contents

Contents

Contents i

List of Figures ii

List of Listings iii

1 Introduction 1

2 Implementation 2

2.1 Server-Side API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2.1.1 Categories for section: /getBrowseCategories . . . . . . . . . . . . . . 3

2.1.2 Search: /search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.1.3 Result set: /getResultSet . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.1.4 User in role: /isUserInRole . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.1.5 Promoted events: /getPromotedEvents . . . . . . . . . . . . . . . . . . 8

2.1.6 Detail: /getDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.1.7 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.2 Client-Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.2.1 Newsticker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3 Functionality of the iPhone application 14

3.1 Sections/Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.2 Login - Cluster members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.3 Records details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.4 Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.5 Newsticker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

i


5/23

List of Figures

List of Figures

1 iPhone - Server: Request - Response example . . . . . . . . . . . . . . . . . . . 122 Simple class-diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3 Section view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4 Category view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5 Section "person" - user not logged in . . . . . . . . . . . . . . . . . . . . . . . . 15

6 Wrong password or username . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

7 User logged in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

8 Company . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

9 Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1510 Person . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

11 Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

12 Search in section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

13 Search in category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

14 Static message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

15 Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

16 Event detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

ii


6/23

Listings

Listings

1 Example response for all categories in section "event". . . . . . . . . . . . . . . 32 Result-Set for records in category "Kongress". . . . . . . . . . . . . . . . . . . . 5

3 Result-Set for search in category. . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 Result-Set for search in section. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

5 Response from isUserInRole, the user has no rights. . . . . . . . . . . . . . . . 7

6 Promoted events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

7 Details for "event" with ID 415 . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

8 No/invalid API key provided . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

9 Wrong/too few arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110 Access of secure service in public environment . . . . . . . . . . . . . . . . . . . 11

iii


7/23

1 Introduction

1 Introduction

The clusterinfo.at iPhone application is the mobile access point for the existing clusterinfo.atweb portal and CRM system. For accessing the portal a completely new REST-API has been

developed which provides direct access to the database.

Like the web portal, the App allows the user to search the public database.

Further features:

Search in section: company, event, person

Search in category

Show address in map

Write in-app email

Open links in browser

Call telephone numbers

The section "person" is only available for cluster members.

This paper also provides a detailed documentation of the implemented REST webservice

API, the implementation of the client and an overview of the functionality of the application.

1


8/23

2 Implementation

2 Implementation

The CIS (clusterinformation system) provides a REST webservice to access all information ofthe clustersystem. The webservice provides public and secure (HTTP-Basic-Auth, username/-

password) access over SSL (secure socket layer). The service responds with an XML document

encoded in ISO-8859-1 over the following URLs:

Public: https://www.clusterinfo.at/mobile/services/

Secure: https://www.clusterinfo.at/mobile/services/secure/

For several requests (e.g. /search) the webservice only returns a result set. In this case,

the webservice executes a query and returns an XML response with "metadata" about the

search like the "set id" generated on the server and the number of records found.

The set contains all records found (on the server). The results (records) can be requested

with another service later on - this means that not all records are returned intermediately to the

client. This mechanism has several advantages: fast and small response, instant information

about the search, "browsing" through the set or only get a range of records.

2.1 Server-Side APIThe server-side API provides the following services:

/getBrowseCategories (see 2.1.1)

/getResultSet (see 2.1.3)

/isUserInRole (see 2.1.4)

/search (see 2.1.2)

/getPromotedEvents (see 2.1.5)

/getDetail (see 2.1.6)

2


9/23

2 Implementation

All services can be accessed either publicly or securely except /isUserInRole, which can

only be accessed securely. For every request the apiKey attribute (access token) has to be

provided to ensure an authorized access from the iPhone application.

The root node () of the XML response has the following attributes:

status: status of the request: OK or ERROR

searchHits: number of retrieved search results

setId: ID of the generated set (only /search)

2.1.1 Categories for section: /getBrowseCategories

Returns the categories (with attributes FIXED/DYNAMIC) for a specific section.

Arguments:

type: {company|person|event} (section)

Example: All categories for the section "event".

Request: /getBrowseCategories?apiKey=1234&type=event

Response:

1 < ? x m l v e r si o n = " 1 . 0 " e n c od i n g = " I SO - 8 85 9 - 1 " ? >

2 < r : r e s ul t s t a tu s = " O K " x m l ns : r = " h t t p: / / w w w . h e a l t h ga t e . a t /

H T S M o b i l e R e s u l t " >

3 < r : c a t e go r y t y pe = " F I X E D " >

4 < r : i d > 7 9 9 9 9 9 9 9 9 9 9 9 9 0 0 1 < / r : i d >

5 < r : c a t N a m e > K o n g r e s s < / r : c a t N a m e >

6

< / r : c a t e g o r y >7 < r : c a t e go r y t y pe = " F I X E D " >

8 < r : i d > 7 9 9 9 9 9 9 9 9 9 9 9 9 0 0 2 < / r : i d >

9

10 < r : c a t N a m e > S e m i n a r < / r : c a t N a m e >

3


10/23

2 Implementation

11 < / r : c a t e g o r y >


13 < r : i d > 7 9 9 9 9 9 9 9 9 9 9 9 9 0 0 3 < / r : i d >14 < r : c a t Na m e > Q u a l i f i z i e r un g s w o r k sh o p < / r : c a t N a me >

15 < / r : c a t e g o r y >


17

18 < r : i d > 7 9 9 9 9 9 9 9 9 9 9 9 9 0 0 4 < / r : i d >

19 < r : c a t N a m e > M e s s e n < / r : c a t N a m e >

20 < / r : c a t e g o r y >


22 < r : i d > 7 9 9 9 9 9 9 9 9 9 9 9 9 0 0 5 < / r : i d >

23 < r : c a t Na m e > F a c h v e r a n s ta l t u n g < / r : c a tN a m e >

24 < / r : c a t e g o r y >

25


27 < r : i d > 7 9 9 9 9 9 9 9 9 9 9 9 9 0 0 6 < / r : i d >

28 < r : c a t Na m e > F a s t F o r wa r d < / r : c a t Na m e >

29 < / r : c a t e g o r y >


31 < r : i d > 7 9 9 9 9 9 9 9 9 9 9 9 9 0 0 7 < / r : i d >

32

< r : c a t Na m e > F a s t F o r wa r d S u c ce s s < / r : c a t N am e >33

34 < / r : c a t e g o r y >


36 < r : i d > 7 9 9 9 9 9 9 9 9 9 9 9 9 0 0 8 < / r : i d >

37 < r : c a t N a m e > S o n s t i g e < / r : c a t N a m e >

38 < / r : c a t e g o r y >

39 < / r : r e s u l t >

Listing 1: Example response for all categories in section "event".

4


11/23

2 Implementation

2.1.2 Search: /search

This service is the main service for searching in sections, categories and for retrieving records

in categories. Therefore the API needs several arguments:

Arguments:

Search in section:


query: search term

Search in category:


query: search term

categoryId: ID of the category

Records in category:


categoryId: ID of the category

The service only returns a result set (see 2.1.3).

Example 1: Records in category "Kongress".

Request: /search?categoryId=7999999999999001&type=event&apiKey=1234

Response:


2 < r : r e s ul t s t a tu s = " O K " r e s u lt S e t I d = " 1 2 8 5 2 4 8 31 7 9 5 7 9 1 14 3 1 0 7 1 33 "

s e a r ch H i t s = " 2 " x m l ns : r = " h t t p: / / w w w . h e a l t h g at e . a t / H T S M o b i l eR e s u l t " / >

Listing 2: Result-Set for records in category "Kongress".

5


12/23

2 Implementation

Example 2: Search for "zukunft" in category "Kongress".

Request: /search?categoryId=7999999999999001&type=event&query=zukunft&apiKey=1234

Response:




Listing 3: Result-Set for search in category.

Example 3: Search for "zukunft" in section "event".

Request: /search?type=event&query=zukunft&apiKey=1234

Response:




Listing 4: Result-Set for search in section.

2.1.3 Result set: /getResultSet

Returns all records from a given set in a defined range.

Arguments:

setId: ID of the set (retrieved from the /search service)

from: Start index

to: End index

6


13/23

2 Implementation

Example: Get records from set "128524852912191143107133".

Request: /getResultSet?setId=128524852912191143107133&from=1&to=3&apiKey=1234

Response: Records from index 1 to 3.

2.1.4 User in role: /isUserInRole

Check if the current session user has a given role - either returns true or false in the XML

response.

This is a secure service. Public access is not permitted.

Arguments:

roleName: the role to check (e.g. "clusterRights").

Example: The current user has "clusterRights"?

Request: /secure/isUserInRole?apiKey=1234&roleName=clusterRights

Response:


2 < r : r e s ul t s t a tu s = " O K " x m l ns : r = " h t t p: / / w w w . h e a l t h ga t e . a t /

H T S M o b i l e R e s u l t " >

3 < r : u s e r I n R o l e > f a l s e < / r : u s e r I n R o l e >

4 < / r : r e s u l t >

Listing 5: Response from isUserInRole, the user has no rights.

7


14/23

2 Implementation

2.1.5 Promoted events: /getPromotedEvents

Returns all promoted events - the returned XML is equal to the response when the service

/search?type=event is requested.

Example: All promoted events.

Request: /getPromotedEvents?apiKey=1234

Response:


2 < r : r e s ul t s t a tu s = " O K " s e a r ch H i t s = " 1 " x m l ns : r = " h t t p: / / w w w . h e a l t h g at e . a t

/ H T S M o b i l eR e s u l t " x m l n s: e = " h t t p : / / w ww . h e a l t h g a te . a t / H T S M o b i l e E ve n t " >

3 < r : e v e n t >

4 < e : v e r a n s ta l t u n g sI d > 4 1 5 < / e : v e r a n s t al t u n g s Id >

5 < e : t i te l > Z u k u n f t s k o n fe r e n z 2 0 10 - n e xt g e n e ra t i o n < / e : t i te l >

6 < e : v e r a n s ta l t u n g sA r t > K o n g r e s s < / e : v e r a ns t a l t u ng s A r t >

7 < e : i n h al t > - H u m an R e s o ur c e s u n d I n n o v a ti o n s m a n ag e m e n t < /

e : i n h a l t >

8 < e : v e r a n st a l t e r > H u m an . t e c h n o l o g y S t y ri a G m bH < / e : v e r a n s t al t e r >

9 < e : z i e l p u b l i k u m / >

10 < e : s f g Li n k c T yp e = " U R L " / >11 < e : e v e n tL i n k c T yp e = " U R L " / >

12 < e : a n f a h r t / >

13 < e : g e b u e h r M i t g l > 3 5 < / e : g e b u e h r M i t g l >

14 < e : g e b u e h rN i c h t M it g l > 1 6 0 < / e : g e b u e h r Ni c h t M i tg l >

15

16 < e : m a x T e il n e h m e r > 2 1 4 7 4 83 6 4 7 < / e : m a x T e i ln e h m e r >

17 < e : a n m e l d eS c h l u ss > 2 0 1 0 09 2 1 < / e : a n m e l d eS c h l u s s >

18 < e : h i n w e i s e / >

19 < e : d a t u m V o n > 2 0 1 0 0 9 2 3 < / e : d a t u m V o n >

20 < e : z e i t V o n > 0 9 : 3 0 < / e : z e i t V o n >

21 < e : d a t u m B i s > 2 0 1 0 0 9 2 3 < / e : d a t u m B i s >

22

23 < e : z e i t B i s > 1 7 : 0 0 < / e : z e i t B i s >

8


15/23

2 Implementation

24 < e : o r t > S e i f e n f a b r i k V e r a n s t a l t u n g s z e n t r u m ,

25 A n g e rg a s s e 4 1 - 4 3 , 8 0 10 G r az < / e : o r t >

26 < / r : e v e n t >27 < / r : r e s u l t >

Listing 6: Promoted events

2.1.6 Detail: /getDetail

This service provides direct access to a record (company/person/event) without requesting it

with /search and /getResultSet.

Arguments:

recordId: ID of the record

type: {company|person|event}

Example: Get "event" record with ID 415.

Request: /getDetail?recordId=415&type=event&apiKey=1234

Response:


2 < r : r e s ul t s t a tu s = " O K " s e a r ch H i t s = " 1 " x m l ns : r = " h t t p: / / w w w . h e a l t h g at e . a t

/ H T S M o b i l eR e s u l t " x m l n s: e = " h t t p : / / w ww . h e a l t h g a te . a t / H T S M o b i l e E ve n t " >

3 < r : e v e n t >

4 < e : v e r a n s ta l t u n g sI d > 4 1 5 < / e : v e r a n s t al t u n g s Id >

5 < e : t i te l > Z u k u n f t s k o n fe r e n z 2 0 10 - n e xt g e n e ra t i o n < / e : t i te l >

6 < e : v e r a n s ta l t u n g sA r t > K o n g r e s s < / e : v e r a ns t a l t u ng s A r t >

7 < e : i n h al t > - H u m an R e s o ur c e s u n d I n n o va t i o ns m a n ag e m e n t , . . . < /

e : i n h a l t >

8

9 < e : v e r a n st a l t e r > H u m an . t e c h n o l o g y S t y ri a G m bH < / e : v e r a n s t al t e r >

10 < e : z i e l p u b l i k u m / >

9


16/23

2 Implementation

11 < e : s f g Li n k c T yp e = " U R L " / >

12 < e : e v e n tL i n k c T yp e = " U R L " / >

13 < e : a n f a h r t / >14 < e : g e b u e h r M i t g l > 3 5 < / e : g e b u e h r M i t g l >

15 < e : g e b u e h rN i c h t M it g l > 1 6 0 < / e : g e b u e h r Ni c h t M i tg l >

16

17 < e : m a x T e il n e h m e r > 2 1 4 7 4 83 6 4 7 < / e : m a x T e i ln e h m e r >

18 < e : a n m e l d eS c h l u ss > 2 0 1 0 09 2 1 < / e : a n m e l d eS c h l u s s >

19 < e : h i n w e i s e / >

20 < e : d a t u m V o n > 2 0 1 0 0 9 2 3 < / e : d a t u m V o n >

21 < e : z e i t V o n > 0 9 : 3 0 < / e : z e i t V o n >

22 < e : d a t u m B i s > 2 0 1 0 0 9 2 3 < / e : d a t u m B i s >

23

24 < e : z e i t B i s > 1 7 : 0 0 < / e : z e i t B i s >

25 < e : o r t > S e i f e n f a b r i k V e r a n s t a l t u n g s z e n t r u m ,

26 A n g e rg a s s e 4 1 - 4 3 , 8 0 10 G r az < / e : o r t >

27 < / r : e v e n t >

28 < / r : r e s u l t >

Listing 7: Details for "event" with ID 415

2.1.7 Error handling

The webservice returns a number of various error messages indicated by the status attribute

("ERROR") of the node.

Error messages:

No/invalid API key provided (see listing 8)

Wrong/too few arguments (see listing 9)

Access of secure service in public environment (see listing 10)

10


17/23

2 Implementation

1 < r : r e s ul t s t a tu s = " E R R O R " >

2 < r : e r r o rM s g > I n v a l i d A pi K e y < / r : e r r o rM s g >

3 < / r : r e s u l t >

Listing 8: No/invalid API key provided


2 < r : e r r o rM s g > I n v a l i d A r gu m e n t s < / r : e r r or M s g >

3 < / r : r e s u l t >

Listing 9: Wrong/too few arguments


2 < r : e r r o rM s g > N o P u b l i c Ac c e s s < / r : e r r o rM s g >

3 < / r : r e s u l t >

Listing 10: Access of secure service in public environment

11


18/23

2 Implementation

2.2 Client-Side

Figure 1: iPhone - Server: Request - Response example

Figure 1 shows the main concept of performing a search request:

1. Client-Request: The client request the result set for the query, e.g. "zukunft":

/search?type=event&query=zukunft&apiKey=1234.

2. Webservice-Response: The server responds with the result set containing the set id and

the number of found records - searchHits (see listing 4 for example).

3. Client-Request: If the webservice returns searchHits > 0 the client performs the next

request to get a number of records or all records from the set

(e.g. /getResultSet?setId=128524852912191143107133&from=1&to=3&apiKey=1234)

otherwise the client does not need to perform additional requests.

4. Webservice-Response: The service returns all records belonging to the given result set.

The connection to the REST-API is handled by a delegate implementation of NSURLConnection

which is held by the specific data source of each section. The parsing is done with NSXMLParser

which fulfills the required needs.

Each section has its own data source (CISectionDataSource/CICategoryDataSource) which

implements the delegate protocol of CIURLConnection and CIParser (with all subclasses) to

handle the received data - parsing, error handling.

12


19/23

2 Implementation

Figure 2 shows the relation between all implemented classes.

CIBaseEntity

C I Co m pa n yE n ti t y C IP e rs o nE n ti t y C IE ve n tE n ti t y C I Ca t eg o ry E nt i ty

CIParser

C IE nt it yP ar se r C IC at eg or yP ar se r C IR es ul tP ar se r C IU se rR ol eP ar se r

CICategoryTableViewControllerCISearchTableControllerCISectionTableViewController

PeopleSectionTableViewController

clusterinfo_atAppDelegate SettingsTableViewController

AboutViewController

C IS e ct io n Da t aS o ur c e C IC a te g or yD a ta S ou r ce

CIURLConnection

CIUser

CITickerView

CISettingsCell

CILoadNextCell

CIActivityView

CIEntityTableViewController

CIMapViewController

CIDetailTableViewController

AddressAnnotation

CITickerMessageParser

Figure 2: Simple class-diagram

2.2.1 Newsticker

The newsticker shows messages from a static XML-File (parsed with CITickerMessageParser)

and promoted events (service /getPromotedEvents). All messages are loaded at program

startup. If the user performs a login or logout the messages are flushed and reloaded.

13


20/23

3 Functionality of the iPhone application


This section shows the functionality of the clusterinfo.at application. The following imagesrefer to all sections.

3.1 Sections/Categories

Figures 3 and 4 show the main view for each section and category.

Figure 3: Section view Figure 4: Category view

14


21/23


3.2 Login - Cluster members

The section "person" (figure 5) is only available for cluster members. Therefore the settings

page provides the a login form (figure 7).

Figure 5: Section "person" -user not logged in

Figure 6: Wrong password orusername

Figure 7: User loggedin

3.3 Records details

Figure 8: Company Figure 9: Event Figure 10: Person Figure 11: Address

15


22/23


The following attributes of an records can be accessed:

Address opens map view

Telephone number call number

Web address opens browser

Email opens in-app email client

3.4 Search

The application provides functionality for searching a whole section as well as searching a singlecategory. In order to perform a search request the table needs to be scrolled down.

The application provides searching a whole section (figure 12) and searching only in a section

(figure 13) - to do this, the table need to scrolled down.

Figure 12: Search in section Figure 13: Search in category

16


23/23


3.5 Newsticker

The newsticker displays promoted events (indicated by ">", figure 15) which can be touched

in order to show further details (figure 16) and static messages (figure 14).

Figure 14: Static message Figure 15: Event Figure 16: Event detail

iphone app - clusterinfo.at

Documents