Mobiliser Framework Development Guide SAP Mobile Platform - Mobiliser 5.5 Copyright c 2015 SAP AG. All rights reserved. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, SAP HANA, 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 other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business Objects is an SAP company. Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase Inc. Sybase is an SAP company. Crossgate, m@gic EDDY, B2B 360, and B2B 360 Services are registered trademarks of Crossgate AG in Germany and other countries. Crossgate is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. Contents 1 Introduction 15 2 Getting Started 16 2.1 Development Environment...................................... 16 2.1.1 Prerequisites.......................................... 16 2.1.2 Hardware and OS....................................... 16 2.1.3 Java.............................................. 17 2.1.4 Integrated Development Environment............................ 17 2.1.5 Source Control......................................... 17 2.1.6 Build Tool........................................... 18 2.1.7 Database........................................... 19 2.2 Build Environment........................................... 20 2.2.1 Nexus............................................. 20 2.2.2 Jenkins............................................. 22 2.2.3 Sonar............................................. 22 3 Customization Project Conventions 23 3.1 Customization Template........................................ 23 3.2 Project Structure........................................... 23 3.3 Module Structure........................................... 25 3.3.1 pom.xml............................................ 26 3.3.2 bundle-context-osgi.xml.................................... 26 3.4 Dist Module.............................................. 28 3.4.1 The POM File......................................... 28 3.4.2 Dist Assembly......................................... 34 4 Persistence 36 4.1 Schema................................................ 36 4.1.1 Create a PowerDesigner Physical Data Model........................ 38 4.1.2 Create or Modify a Table................................... 39 3 4.1.3 Trigger............................................. 43 4.1.4 Sequences........................................... 43 4.1.5 Migrate Model......................................... 43 4.1.6 Apply Schema Changes................................... 43 4.1.7 Generate DDL......................................... 44 4.1.8 Generate Update Script.................................... 44 4.2 Data Model Beans........................................... 44 4.2.1 Constructors.......................................... 46 4.2.2 Fields............................................. 46 4.2.3 Annotations.......................................... 46 4.2.4 Getter and Setter....................................... 47 4.2.5 isSet-methods......................................... 47 4.2.6 Common Patterns for entity beans.............................. 47 4.2.7 Composite Primary Key.................................... 49 4.3 Data Access Object API........................................ 49 4.3.1 Large Result Sets....................................... 51 4.4 Implementing a DAO......................................... 51 4.4.1 Quick Guide.......................................... 51 4.4.2 DAO Implementation..................................... 52 4.4.3 DAO Factory.......................................... 55 4.4.4 Exception Translation..................................... 56 4.4.5 Persistence Service Provider................................. 57 4.4.6 Caching............................................ 57 4.4.7 JDBC.............................................. 59 4.5 Transaction Demarcation....................................... 60 4.6 Data Scripts.............................................. 60 5 Services 62 5.1 Component Architecture....................................... 62 5.1.1 Transaction Manager..................................... 62 5.1.2 Access Security........................................ 66 5.1.3 Error Handling......................................... 66 5.2 Context................................................. 68 5.3 Contract................................................ 71 5.3.1 Layout............................................. 71 5.3.2 Beans XSD.......................................... 72 4 5.3.3 Requests XSD......................................... 73 5.3.4 POM configuration....................................... 75 5.4 OData................................................. 78 5.4.1 Basics............................................. 78 5.4.2 GET Operation........................................ 80 5.4.3 GetAll Operation........................................ 81 5.4.4 PUT Operation (update).................................... 82 5.4.5 POST Operation (create)................................... 82 5.4.6 MERGE Operation...................................... 84 5.4.7 Links.............................................. 84 5.4.8 General............................................ 86 5.5 Endpoint................................................ 87 5.5.1 Configuration......................................... 87 5.6 Service Aspects............................................ 90 5.6.1 Security Advisor........................................ 90 5.6.2 ResponseCodeAspect.................................... 90 5.6.3 TraceableRequestAspect................................... 91 5.6.4 AuditAspect.......................................... 91 5.6.5 SessionInterceptor...................................... 91 5.6.6 TransactionInterceptor..................................... 91 5.6.7 Service Filters......................................... 92 5.6.8 Custom Service Aspects................................... 94 5.7 Service Business Logic........................................ 95 5.7.1 Converter........................................... 96 5.7.2 Service Business Logic.................................... 98 5.7.3 Configuration......................................... 101 5.8 Mobiliser Virus Scan Framework................................... 102 5.8.1 Usage............................................. 103 5.9 Using Services............................................ 104 5.9.1 Within the Container...................................... 104 5.9.2 Outside the Container..................................... 105 6 Audit 108 7 Security 111 7.1 Filters................................................. 111 7.2 Authentication............................................. 111 5 8 Preferences 114 8.1 Using Preferences........................................... 114 8.2 Accessing Preferences from within the container.......................... 116 8.3 Accessing Preferences outside the container............................ 117 8.3.1 Configuration......................................... 117 8.4 Extending Preferences........................................ 119 8.4.1 Encryption........................................... 119 8.4.2 Interceptor........................................... 120 9 Events and Alerts 122 9.1 Event Generation API......................................... 122 9.1.1 Header And Body....................................... 122 9.1.2 Event Factory......................................... 126 9.1.3 Regular Events........................................ 127 9.1.4 Conditional Events...................................... 128 9.1.5 Scheduled Events....................................... 130 9.1.6 Transient Events........................................ 133 9.2 Event Handling API.......................................... 134 9.2.1 Abstract Event Handler.................................... 135 9.2.2 Serial Event Handler..................................... 137 9.2.3 Parallel Event Handler..................................... 138 9.2.4 Event Handler Registration.................................. 139 9.3 Task Handling API........................................... 140 9.3.1 Abstract Task Handler..................................... 140 9.3.2 Task Handler Registration................................... 143 9.4 System Bundles and Services.................................... 143 9.4.1 OSGi Configuration Admin Properties...........................