sup_tutorial_ios_object_api_application_development
sup_tutorial_ios_object_api_application_development
Development
Sybase Unwired Platform 2.2
SP04
DOCUMENT ID: DC01213-01-0224-01
LAST REVISED: May 2013
Copyright © 2013 by Sybase, Inc. All rights reserved.
This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions or
technical notes. Information in this document is subject to change without notice. The software described herein is furnished
under a license agreement, and it may be used or copied only in accordance with the terms of that agreement.
Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced,
transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior
written permission of Sybase, Inc.
Sybase trademarks can be viewed at the Sybase trademarks page at http://www.sybase.com/detail?id=1011207. Sybase and
the marks listed are trademarks of Sybase, Inc. ® indicates registration in the United States of America.
SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered
trademarks of SAP AG in Germany and in several other countries all over the world.
Java and all Java-based marks are trademarks or registered trademarks of Oracle and/or its affiliates in the U.S. and other
countries.
Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.
All other company and product names mentioned may be trademarks of the respective companies with which they are
associated.
Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS
52.227-7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.
Sybase, Inc., One Sybase Drive, Dublin, CA 94568.
Contents
Sybase Unwired Platform Tutorials ......................................1
Getting Started with Unwired Platform ................................3
Installing Sybase Unwired Platform ................................3
Starting Sybase Unwired Platform Services ...................4
Starting Sybase Unwired WorkSpace ............................4
Connecting to Sybase Control Center ............................5
Learning Sybase Unwired WorkSpace Basics ...............5
Developing an iOS Application ............................................9
Installing Xcode IDE .....................................................10
Generating Object API Code ........................................10
Setting Up an iOS Client Application in Xcode .............12
Adding Source Code Files, Libraries, and
Resources to the Xcode Project ......................13
Configuring the Build Settings .............................14
Registering the Application Connection in Sybase
Control Center ..........................................................16
Viewing the CallbackHandler and
ApplicationCallbackHandler Files .............................17
Creating the User Interface ...........................................17
Viewing the SubscribeController View Controller
.........................................................................18
Creating the MenuListController ..........................30
Creating the CustomerListController ...................31
Adding the DetailController and Configuring the
View .................................................................31
Deploying the Device Application .................................34
Learn More About Sybase Unwired Platform ....................39
Index ..................................................................................41
• Development support for native Object API applications, HTML5/JS Hybrid Apps,
and native OData SDK applications.
• Sybase Unwired WorkSpace, the Eclipse-based development environment for MBOs
and Hybrid Apps.
Next
To read more about Sybase Unwired WorkSpace concepts and tasks, select Help > Help
Contents.
1. Select Start > Programs > Sybase > Sybase Control Center.
Note: If Sybase Control Center does not launch, make sure that the Sybase Control Center
service is started in the Windows Services dialog.
2. Log in by entering the credentials set during installation.
Sybase Control Center gives you access to the Unwired Platform administration features
that you are authorized to use.
Window Description
WorkSpace Navigator view Use this view to create Mobile Application projects,
and review and modify MBO-related properties.
This view displays mobile application project fold-
ers, each of which contains all project-related re-
sources in subfolders, including MBOs, datasource
references to which the MBOs are bound, personal-
ization keys, and so on.
Window Description
Palette The Palette is accessed from the Mobile Application
Diagram and provides controls, such as the ability to
create MBOs, add attributes and operations, and de-
fine relationships, by dragging and dropping the
corresponding icon onto the Mobile Application Di-
agram or existing MBO.
Outline view Displays an outline of the active file and lists struc-
tural elements. The contents are editor-specific.
Prerequisites
Note: This tutorial has been developed using Sybase Unwired Platform 2.2 SP04, Mac OS X
10.8.2, iOS SDK 6.1, and Xcode 4.6 Development Environment, and executed on an iOS
Simulator v 6.1. If you use a different version, some steps may vary. For more information on
Xcode, refer to the Apple Developer Connection: http://developer.apple.com/technologies/
tools/whats-new.html.
1. Complete the tasks in Getting Started with Unwired Platform.
2. Either:
• create the MBO project by completing Tutorial: Mobile Business Object
Development, or
• download and deploy the MBO SUP101 example project (complete project files) from
the SAP® Community Network: http://scn.sap.com/docs/DOC-8803.
Note: If you upgrade Sybase Mobile SDK after completing the tutorial, you can convert
the project to the current SDK by importing the earlier project into the Unwired Workspace
and then accepting the confirmation prompt.
3. (Optional) To use as a reference and copy source code when completing this tutorial,
download the iOS SUP 101 example project (source code only) from the SAP®
Community Network: http://scn.sap.com/docs/DOC-8803.
Task
Option Description
Language Select Objective C.
Platform Accept the default, iOS.
Unwired Server Select My Unwired Server.
Server domain Accept default. If you are not connected to
Unwired Server, this field is empty. Connect to
Unwired Server to proceed.
Option Description
Page size Accept the default or select a larger page size.
Name prefix The prefix for the generated files. Leave blank.
Project path Accept the default or enter a different location
for the generated project files.
(Optional) Clean up destination before code Delete all items in the destination folder before
generation generating the device client files.
Objective-C code is generated into the specified output location and in the WorkSpace
Navigator.
Prerequisites
• Generate Objective-C code in to an output location.
• Verify that Sybase Unwired Platform is installed in a shared directory so you can access it
from your Mac.
• To help create your project, and to later build the interface, download and import the
SUP101 iOS Object API (2.2 SP04) example project from the SAP Community Network
(SCN) at http://scn.sap.com/docs/DOC-8803.
• Copy the SUP101 iOS Object API example project to your Mac machine and extract it into
a folder. The example project contains the Xcode project and a SUP101 project archive file
to use in Sybase Unwired WorkSpace.
Task
1. On your Mac, start Xcode and select Create a new Xcode project.
2. Select iOS Application and Single View Application as the project template, and then
click Next.
3. Specify these values and click Next.
a) Enter SUP101 as the product name.
b) Enter MyCorp (or another value as needed) as the company identifier.
c) Select SUP101 for the class prefix.
d) Select Universal as the device family product.
e) Unselect Use Storyboards.
f) Unselect Use Automatic Reference Counting.
g) Unselect Include Unit Tests.
4. Select a location in which to save the project and click Create to open it.
Xcode creates a folder, SUP101, to contain the project file, SUP101.xcodeproj, and
another SUP101 folder, which contains a number of automatically generated files and a
build folder.
5. Delete some of the automatically generated files created by default for the Xcode project.
a) In Xcode, delete the SUP101 folder under the SUP101 project:
1. Click Remove References.
2. In the Finder, manually delete the SUP101 folder from the project folder.
3. Verify that only the SUP101.xcodeproj file and the build folder are in the
SUP101 folder.
6. Verify that the SDK and deployment targets are correct:
a) Select SUP101 in Project Navigator and then select Build Settings.
b) Under Project, select SUP101.
c) Verify that Base SDK under Architectures is set to Latest iOS (iOS 6.1).
d) Scroll to the Deployment section and set the iOS Deployment Target to iOS 4.3 or
higher.
e) Select Targets > SUP101 and verify that those values are also set.
7. Copy the files from the SUP101 folder on your Windows machine to the SUP101 folder
on your Mac that Xcode created to contain the SUP101 project:
a) Connect to the Microsoft Windows machine where Sybase Unwired Platform is
installed
b) From the Apple Finder menu, select Go > Connect to Server.
c) Enter the name or IP address of the machine, for example, smb://<machine DNS
name> or smb://<IP Address>, then click Connect.
You see the shared directory.
d) Copy the SUP_HOME\MobileSDK22\ObjectAPI\iOS folder from the
Unwired Platform installation directory to the SUP101 folder on your Mac.
e) On your Windows machine, navigate to the SUP101 mobile application project and
copy the Generated Code folder to the SUP101 directory on your Mac.
Next
Add libraries, resources, and source code to the SUP101 Xcode project.
See also
• Registering the Application Connection in Sybase Control Center on page 16
1. In the Xcode Project Navigator, Ctrl-click the SUP101 project, then select Add Files to
"SUP101".
Select the Generated Code folder, unselect Copy items into destination group's
folder (if needed), and click Add.
The Generated Code folder is added to the project in the Project Navigator.
Next
Configuring the build settings.
1. In the right pane, click the Build Settings tab and scroll down to the Search Paths section.
Enter the location of the iPhone simulator libraries in the Header Search Paths and Library
Search Paths fields.
$SRCROOT is a macro that expands to the directory where the Xcode project file resides.
Adding this macro in front of the path is optional.
• In Header Search Paths, enter the path to the iOS/includes directory, then select
the recursive option. In this example, the path is indicated as iOS/includes/**.
• In Library Search Paths, specify profiles for Debug and Release. In this example, the
path is indicated as "iOS/Libraries/$(CONFIGURATION)$
(EFFECTIVE_PLATFORM_NAME)". Escape the path names using double quotes.
2. In the right pane, select the Build Phases tab, then expand the Link Binary with
Libraries section.
Click the + icon below the list, select the following libraries, and then click Add to add
them to the project:
• CFNetwork.framework
• CoreFoundation.framework
• CoreGraphics.framework
• Foundation.framework
• libicucore.A.dylib
• libstdc++.dylib
• libz.dylib
• MobileCoreServices.framework
• Security.framework
• SystemConfiguration.framework
3. In the right pane, select the Build Phases tab, then expand the Copy Bundle Resources
section. Select SUP101-info.plist and click on the - sign to remove it.
4. Hold the Option key, and select Product > Clean Build Folder, then Product > Build to
test initial project setup. If you correctly followed this procedure, you see a Build
Succeeded message.
Prerequisites
Connect to Sybase Control Center.
Task
1. Log in to Sybase Control Center using the credentials you indicated during installation.
2. In Sybase Control Center, select View > Select > Unwired Server Cluster Management
View.
3. In the left pane, select Applications.
4. In the right pane, click Application Connections.
5. Click Register.
6. In the Register Application Connection window, enter the required information:
• User name – user1
• Template – SUP101_admin
• Application ID – SUP101
• Security configuration – admin
• Logical role – leave blank or use the logical role when you assigned to this user during
the deployment to Server
• Domain – default
• Activation code length – 3
• Activation expiration (hours) – 72
• Specify activation code – 123
7. Click OK.
Next
In Xcode, view the application source files and walk through how they are created.
See also
• Setting Up an iOS Client Application in Xcode on page 12
See also
• Deploying the Device Application on page 34
1. In the SUP101 Xcode project, click SubscribeController.m to view the logic for
the view controller.
2. Click SubscribeController.h to view the header file.
See also
• Creating the MenuListController on page 30
• Creating the CustomerListController on page 31
• Adding the DetailController and Configuring the View on page 31
if(self.firstRun)
{
NSLog(@"Running the app for the first time.");
@try {
NSLog(@"Create new SUP101 data vault and store credentials and a
generated encryption key");
sup101vault = [SUPDataVault createVault:kSUP101DataVaultID
withPassword:self.pin withSalt:kSUP101DataVaultSalt]; // creates the
vault
[sup101vault setString:@"password" withValue:self.password];
if (![sup101vault isLocked])
{
[sup101vault lock];
}
}
@catch (NSException *exception) {
NSLog(@"Exception in creating new SUP101 data vault: %@: %@",
[exception name], [exception reason]);
[self showNoTransportAlert:kSUP101ErrorFailure];
return;
}
@try {
NSLog(@"Create new messaging vault and leave it unlocked");
messagingvault = [SUPDataVault createVault:kMessagingDataVaultID
withPassword:self.pin withSalt:kDVStandardSalt];
}
@catch (NSException *exception) {
NSLog(@"Exception in creating new messaging data vault: %@: %@",
[exception name], [exception reason]);
[self showNoTransportAlert:kSUP101ErrorFailure];
return;
}
}
else
{
// If the application has been run before, we get the PIN from the
user, and use it to unlock the existing messaging data vault
// (otherwise the messaging layer cannot start).
NSLog(@"App has been run before.");
@try {
NSLog(@"Unlock messaging vault");
messagingvault = [SUPDataVault getVault:kMessagingDataVaultID];
if ([messagingvault isLocked])
{
[messagingvault unlock:self.pin withSalt:kDVStandardSalt];
}
}
@catch (NSException *exception) {
NSLog(@"Exception unlocking messaging data vault: %@: %@",[exception
name],[exception reason]);
[self showNoTransportAlert:kSUP101ErrorBadPin];
return;
}
This code sample sets up the notification observers and the Application API settings for
connection to the Unwired Server and registers with the Unwired Server.
// Add the observer to listen for ON_REGISTER_SUCCESS or
ON_CONNECT_SUCCESS if its the first run or
// subsequent runs respectively.Refer the comments in
registerObserverForCallbackNotifications.
// The observer must be added before the call to registerApplication,
but after applicationIdentifier is
// set and the messaging vault unlocked. (AppIdentifier being set and
vault being unlocked are prerequisites to
if ([sController
respondsToSelector:@selector(registerObserverForCallbackNotificatio
ns)])
{
[sController
performSelector:@selector(registerObserverForCallbackNotifications)
];
}
@try {
sup101vault = [SUPDataVault getVault:kSUP101DataVaultID];
if ([sup101vault isLocked])
{
[sup101vault unlock:self.pin withSalt:kSUP101DataVaultSalt];
}
else
{
login.username = self.userName;
login.password = [sup101vault getString:@"password"];
props.activationCode = nil;
}
props.loginCredentials = login;
}
@catch (SUPPersistenceException * pe) {
NSLog(@"%@: %@", [pe name],[pe message]);
[self showNoTransportAlert:kSUP101ErrorFailure];
return;
}
@catch (NSException* e) {
NSLog(@"%@: %@", [e name],[e reason]);
[self showNoTransportAlert:kSUP101ErrorFailure];
return;
}
@finally
{
if (![sup101vault isLocked])
{
[sup101vault lock];
}
}
@try {
// Initialize generated package database class with this application
instance.
[SUP101SUP101DB setApplication:app];
}
@catch (SUPApplicationTimeoutException* tex)
{
NSLog(@"%@: %@", [tex name],[tex message]);
[self showNoTransportAlert:kSUP101ErrorFailure];
return;
}
@catch (NSException *e)
{
// When we are faced with a registeration error or connection error,
the 'onRegistrationStatusChanged'
// or on 'onConnectionStatusChanged' callbacks are triggered in which
we send the ON_CONNECT_FAILURE
// notification or the ON_REGISTER_FAILURE notification to handle it
// and show the alert window to the user.So we don't have to do it
again here.
// For all other failures, other than the timeout exception above ,
we will handle it here.
if ([SUPApplication registrationStatus] ==
SUPRegistrationStatus_REGISTRATION_ERROR)
{
return;
}
if ([SUPApplication connectionStatus] ==
SUPConnectionStatus_CONNECTION_ERROR)
{
return;
}
• File's Owner – the object that is set to be the owner of the user interface, which is
typically the object that loads the interface. In this tutorial, this is the
SubscribeController.
• First Responder – the first responder proxy object handles events. Connecting an
action to the first responder means that when the action is invoked, it is dynamically
sent to the responder chain.
2. Select the File's Owner icon, click View in the utility area, click Show the Identity
Inspector, and make sure SubscribeController appears in the Class field under
Custom Class.
This tells Interface Builder the class of the object to allow you to make connections to and
from the File's Owner.
3. Click the View icon, and in the Identity Inspector panel, and make sure UIView appears in
the Class field under Custom Class.
4. To create a Subscribe button, select View > Utilities > Show Object Library.
a) In the Object Library pane, select the Round Rect Button item, and drag it onto the
view.
Making Connections
Add Navigation Controllers to MainWindow_iPhone.xib and
MainWindow_iPad.xib, and create a connection from the AppDelegate to the
Navigation Controller.
1. In the left pane, under the iPhone folder, click the MainWindow_iPhone.xib
file.
If you do not see the Navigation Controller in the middle pane, drag it from Objects to the
middle pane:
2. Under Objects in the middle pane, Ctrl-drag from the AppDelegate icon to the Navigation
Controller icon to create a navController outlet.
3. Click the expansion arrow at the bottom of the middle pane to switch to list view, select
Navigation Controller > View Controller, and in the Identity Inspector, select
SubscribeController in the Class field.
Once the class is selected, the ViewController name in the hierarchy changes to
SubscribeController and the connection from the AppDelegate to the Navigation
Controller is created.
4. Repeat steps 1 – 3 to add a navigation controller to MainWindow_iPad.xib.
See also
• Viewing the SubscribeController View Controller on page 18
• Creating the CustomerListController on page 31
• Adding the DetailController and Configuring the View on page 31
See also
• Viewing the SubscribeController View Controller on page 18
• Creating the MenuListController on page 30
• Adding the DetailController and Configuring the View on page 31
@class CallbackHandler;
-(IBAction)buttonPressed:(id)sender;
-(IBAction) keyBoardOff : (id) sender;
-(void)keyBoardOff;
-(void)cleanForm;
-(void)setupNotification;
-(void) reeplaySuccess:(NSNotification *)notification;
-(void) reeplayFailure:(NSNotification *)notification;
@end
12. Ctrl-drag from the File's Owner icon in the middle pane to the Submit button and select
submitButton.
13. Repeat steps 6 – 12 for the Delete button as for the Submit button.
See also
• Viewing the SubscribeController View Controller on page 18
• Creating the MenuListController on page 30
• Creating the CustomerListController on page 31
Prerequisites
Register an application connection in Sybase Control Center.
You must be connected to the server where the mobile application project is deployed.
Task
1. From the top menu, select Product > Edit Scheme to iPhone 6.1 Simulator.
2. Select Product > Build then Product > Run to build the project and start the iPhone
simulator.
3. In the iPhone applications screen, open the SUP101 application.
When you run the application for the first time, it exits immediately with a dialog asking
you to enter the application settings in the Settings application.
4. In the iPhone simulator, go to Settings > SUP101 to enter the connection settings.
• SUP Server – the machine that hosts the server where the SUP101 mobile application
project is deployed.
• SUP Server Port – Unwired Server port number. The default is 5001.
• Farm ID – the company ID you entered when you registered the device in Sybase
Control Center, in this case, 0.
• SUP Username – the user to be authenticated, supAdmin.
If the Manual registration switch is off, the application attempts an automatic registration,
creating an application registration with the same name as the Unwired Platform user
name ("supAdmin" in this example). This allows a client with a valid Unwired Platform
user name and password to connect and register with the server without manual
registration.
If the Manual registration switch is on, the connection name and activation code must be
filled in, and must match an application connection that has already been created in Sybase
Control Center (see Registering the Application Connection in Sybase Control Center).
5. In the iPhone applications screen, reopen the SUP101 application.
Enter a pin with which to securely store your Sybase Unwired Platform password, and a
database encryption key that is generated when the application launches. For subsequent
launches of the application, you need only enter the PIN.
6. Enter a PIN, and enter the password for the Unwired Platform user name entered in step
4.
7. Click Synchronize.
8. Click List.
9. Select a customer record from the customer list and double-click to open the detail view.
The customer detail shows the First Name, Last Name, and Phone.
10. Change the First Name to something else, and click Update.
See also
• Creating the User Interface on page 17
Tutorials
Try out some of the other getting started tutorials available on the Product Documentation
Web site to get a broad view of the development tools available to you.
Example Projects
An example project contains source code for its associated tutorial. It does not contain the
completed tutorial project. Download example projects from the SAP® Community Network
(SCN) at http://scn.sap.com/docs/DOC-8803.
Samples
Sample applications are fully developed, working applications that demonstrate the features
and capabilities of Sybase Unwired Platform.
Check the SAP® Development Network (SDN) Web site regularly for new and updated
samples: https://cw.sdn.sap.com/cw/groups/sup-apps.
Online Help
See the online help that is installed with the product, or available from the Product
Documentation Web site.
Developer Guides
Learn best practices for architecting and building device applications:
• Mobile Data Models: Using Data Orchestration Engine – provides information about
using Sybase Unwired Platform features to create DOE-based applications.
• Mobile Data Models: Using Mobile Business Objects – provides information about
developing mobile business objects (MBOs) to fully maximize their potential.
• SAP Mobile WorkSpace: Mobile Business Object Development – provides information
about using SAP Mobile Platform to develop MBOs and generate Object API code that
can be used to create native device applications and Hybrid Apps.
Use the appropriate API to create device applications:
• Developer Guide: Android Object API Applications
• Developer Guide: BlackBerry Object API Applications
Index
A
application callback handler 17 O
application connection 16
Object API tutorials 1
ApplicationCallbackHandler file 17
Objective-C code, generating 10
C
S
callback handler 17
CallbackHandler file 17 samples
connection, creating 28 downloading 39
customer list view 30, 31 SubscribeController view 24
CustomerListController 30, 31 SUP_iOS_Custom_Dev_Tutorial_code.zip 12
SUP101Appdelegate files 18
Sybase Control Center 16
D connecting to 5
delegate file 18 Sybase Mobile SDK
DetailController.xib 31 installing 3
Sybase Unwired Platform
documentation resources 39
E getting started 3
installing 3
example projects 1
Sybase Unwired WorkSpace
basics 5
G how to access online help 5
starting 4
generating object API code 10
Sybase Unwired WorkSpace basics 5
H
T
Hybrid App package tutorial 1
troubleshooting information 5
tutorials 1
I downloading 39
iOS application, developing 9
iPhone simulator 34 U
M UIViewController subclass 18
Unwired Platform Runtime
MainWindow_iPad.xib 28 installing 3
MainWindow_iPhone.xib 28 Unwired Platform services 4
mobile business object tutorial 1
V
N
view controller, adding 18
navigation controllers 28