Developer Guide: Android Object API Applications - Sybase

212 Pages·2013·1.19 MB·English

by  Sybase, Inc.

Developer Guide: Android Object API
Applications
SAP Mobile Platform 2.3 SP02
DOCUMENT ID: DC01908-01-0232-01
LAST REVISED: April 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
Getting Started with Android Development........................1
Object API Applications..................................................1
Best Uses for Object API Applications............................2
Cache Synchronization..........................................2
Client Runtime Architecture...................................3
Documentation Roadmap for SAP Mobile Platform........4
Development Task Flow for Object API Applications.........5
Installing the Android Development Environment...........6
Installing the Android SDK.....................................7
Installing ADT in SAP Mobile WorkSpace.............7
Installing X.509 Certificates on Android Devices
and Emulators ..................................................7
Generating Java Object API Code..................................8
Generating Java Object API Code Using SAP
Mobile WorkSpace............................................9
Generating Java Object API Code Using the
Code Generation Utility...................................13
Generated Code Location and Contents.............14
Validating Generated Code..................................14
Creating a Project.........................................................15
Creating a Project in SAP Mobile WorkSpace.....15
Downloading the Latest Afaria Libraries..............18
Importing Libraries and Code..............................18
Development Task Flow for DOE-based Object API
Applications.....................................................................19
Installing the Android Development Environment.........20
Installing the Android SDK...................................20
Installing X.509 Certificates on Android Devices
and Emulators ................................................21
Generating Java Object API Code................................22
Generated Code Location and Contents.............23
Developer Guide: Android Object API Applications iii
Contents
Creating a Project.........................................................23
Creating a Project in SAP Mobile WorkSpace.....24
Downloading the Latest Afaria Libraries..............26
Importing Libraries and Code..............................26
Developing the Application Using the Object API............29
Initializing an Application..............................................29
Initially Starting an Application.............................29
Subsequently Starting an Application..................44
Accessing MBO Data....................................................45
Object Queries.....................................................45
Dynamic Queries.................................................46
MBOs with Complex Types..................................47
Relationships.......................................................48
Manipulating Data.........................................................49
Creating, Updating, and Deleting MBO Records
.........................................................................49
Other Operations.................................................50
Using submitPending and
submitPendingOperations...............................51
Shutting Down the Application......................................52
Closing Connections............................................52
Debugging Runtime Errors and Performance Analysis
..................................................................................52
End to End Tracing..............................................52
Tracking KPI.........................................................54
Uninstalling the Application...........................................56
Deleting the Database and Unregistering the
Application.......................................................56
Testing Applications............................................................57
Testing an Application Using a Emulator......................57
Client-Side Debugging..................................................58
Server-Side Debugging................................................59
Improve Synchronization Performance by Reducing
the Log Record Size.................................................60
Determining the Log Record Size........................61
iv SAP Mobile Platform
Contents
Reducing the Log Record Size............................64
Localizing Applications.......................................................67
Packaging Applications......................................................69
Signing..........................................................................69
Client Object API Usage......................................................71
Client Object API Reference.........................................71
Application APIs............................................................71
Application...........................................................72
ConnectionProperties..........................................84
ApplicationSettings..............................................93
ConnectionPropertyType.....................................97
Afaria APIs..................................................................102
Using Afaria to Provision Configuration Data ....102
Using Certificates from Afaria for Authentication
.......................................................................104
Connection APIs.........................................................106
ConnectionProfile..............................................106
Set Database File Property...............................108
Synchronization Profile...............................................109
Connect the Data Synchronization Channel
Through a Relay Server................................109
Asynchronous Operation Replay.......................110
Authentication APIs....................................................110
Logging In..........................................................111
Sample Code: Setting Up Login Credentials.....111
Single Sign-On With X.509 Certificate Related
Object API.....................................................112
Personalization APIs...................................................113
Type of Personalization Keys.............................113
Getting and Setting Personalization Key Values
.......................................................................114
Synchronization APIs..................................................114
Managing Synchronization Parameters.............115
Performing Mobile Business Object
Synchronization.............................................115
Developer Guide: Android Object API Applications v
Contents
Message-Based Synchronization APIs .............116
Push Synchronization Applications....................120
Retrieving Information about Synchronization
Groups...........................................................121
Log Record APIs.........................................................121
LogRecord API..................................................122
Logger APIs.......................................................124
Change Log API.........................................................124
getEntityType.....................................................124
getOperationType..............................................125
getRootEntityType..............................................125
getRootSurrogateKey........................................126
getSurrogateKey................................................126
Methods in the Generated Database Class.......127
Code Samples...................................................128
Security APIs..............................................................129
Encrypt the Database........................................129
End to End Encryption and Compression
Support APIs.................................................130
DataVault...........................................................131
Callback and Listener APIs.........................................150
CallbackHandler API..........................................150
ApplicationCallback API.....................................157
SyncStatusListener API.....................................159
Query APIs.................................................................160
Retrieving Data from Mobile Business Objects. 161
Retrieving Relationship Data.............................169
Back-end Search...............................................170
Persistence APIs.........................................................171
Operations APIs.................................................171
Object State APIs..............................................176
Generated Package Database APIs..................182
Large Attribute APIs...........................................182
MetaData API.............................................................192
MetaData API....................................................192
vi SAP Mobile Platform
Contents
DatabaseMetaData............................................192
ClassMetaData..................................................192
EntityMetaData..................................................192
AttributeMetaData..............................................193
Exceptions..................................................................193
Exception Handling............................................193
Exception Classes.............................................196
Error Codes.......................................................197
Index ................................................................................201
Developer Guide: Android Object API Applications vii
Contents
viii SAP Mobile Platform
Getting Started with Android Development
Getting Started with Android Development
Use advanced SAP® Mobile Platform features to create applications for Android devices. The
audience is advanced developers who may be new to SAP Mobile Platform.
This guide describes requirements for developing a device application for the platform, how to
generate application code, and how to customize the generated code using the Client Object
API. Also included are task flows for the development options, procedures for setting up the
development environment, and Client Object API documentation.
Companion guides include:
• SAP Mobile WorkSpace - Mobile Business Object Development
• Supported Hardware and Software
• Troubleshooting.
• A complete Client Object API reference is available in SMP_HOME
\MobileSDK23\ObjectAPI\apidoc\android
• Fundamentals contains high-level mobile computing concepts, and a description of how
SAP Mobile Platform implements the concepts in your enterprise.
• Developer Guide: Migrating to SAP Mobile SDK contains information for developers
who are migrating device applications to a newer software version, and changes to MBOs,
projects, and the SAP Mobile Server.
Object API Applications
Object API applications are customized, full-featured mobile applications that use mobile
data model packages, either using mobile business objects (MBOs) or Data Orchestration
Engine, to facilitate connection with a variety of enterprise systems and leverage
synchronization to support offline capabilities.
The Object API application model enables developers to write custom code — C#, Java, or
Objective-C, depending on the target device platform — to create device applications.
Development of Object API applications provides the most flexibility in terms of leveraging
platform specific services, but each application must be provisioned individually after being
compiled, even for minor changes or updates.
Development involves both server-side and client-side components. SAP Mobile Server
brokers data synchronization and transaction processing between the server and the client
components.
• Server-side components address the interaction between the enterprise information
system (EIS) data source and the data cache. EIS data subsets and business logic are
Developer Guide: Android Object API Applications 1
Getting Started with Android Development
encapsulated in artifacts, called mobile business object packages, that are deployed to the
SAP Mobile Server.
• Client-side components are built into the mobile application and address the interaction
between the data cache and the mobile device data store. This can include synchronizing
data with the server, offline data access capabilities, and data change notification.
These applications:
• Allow users to connect to data from a variety of EIS systems, including SAP® systems.
• Build in more complex data handling and logic.
• Leverage data synchronization to optimize and balance device response time and need for
real-time data.
• Ensure secure and reliable transport of data.
Best Uses for Object API Applications
Synchronization applications provide operation replay between the mobile device, the
middleware, and the back-end system. Custom native applications are designed and built to
suit specific business scenarios from the ground up, or start with a bespoke application and be
adapted with a large degree of customization.
Cache Synchronization
Cache synchronization allows mapping mobile data to SAP Remote Function Calls (RFCs)
using Java Connector (JCO) and to other non-SAP data sources such as databases and Web
services. When SAP Mobile Platform is used in a stand-alone manner for data
synchronization (without Data Orchestration Engine), it utilizes an efficient bulk transfer and
data insertion technology between the middleware cache and the device database.
In an SAP Mobile Platform standalone deployment, the mobile application is designed such
that the developer specifies how to load data from the back end into the cache and then filters
and downloads cache data using device-supplied parameters. The mobile content model and
the mapping to the back end are directly integrated.
This style of coupling between device and back-end queries implies that the back end must be
able to respond to requests from the middleware based on user-supplied parameters and serve
up mobile data appropriately. Normally, some mobile-specific adaptation is required within
SAP Business Application Programming Interfaces (BAPI). Because of the direct nature of
application parameter mapping and RBS protocol efficiencies, SAP Mobile Platform cache
synchronization deployment is ideal:
• With large payloads to devices (may be due to mostly disconnected scenarios)
• Where ad hoc data downloads might be expected
• For SAP® or non-SAP back ends
Large payloads, for example, can occur in task worker (service) applications that must access
large product catalogs, or where service occurs in remote locations and workers might
2 SAP Mobile Platform