Mobiliser CODE GENERATION - DAO-2-Service

Transcription

1 Mobiliser CODE GENERATION - DAO-2-Service Sybase 365 Mobiliser Platform 5.1

2 Document ID: DC Last Revised: October 15, 2013 Copyright c 2012 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 Sybase and the marks listed are trademarks of Sybase, Inc. R 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. IBM and Tivoli are registered trademarks of International Business Machines Corporation in the United States, other countries, or both. 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 for the DOD and as set forth in FAR (a)-(d) for civilian agencies. Sybase, Inc., One Sybase Drive, Dublin, CA

3 Chapter 1 Introduction There are multiple areas in which code generation for Mobiliser can be helpful, for now we have focused on the area in which we have seen the best cost/benefit ratio. The Mobiliser Framework provides great flexibility when new services are developed. In most cases this flexibility is not required especially when you only want to create CRUD (create, read, update, delete) type services that do not contain much logic but just provide access to the DB through a controlled service layer. In such a scenario a lot of boiler plate code had to be created and the process was error prone. The code generation assumes that the project structure is similar to the project structure proposed by our standard project template. You can change this by providing explicit configurations that overrule the default locations. The code generation works for Mobiliser 5.0 and 5.1 likewise. However, there is a configuration parameter that you should set inthe maven plugin configuration to indicate if you are generating code for 5.0 or 5.1. Please note that the code generation will not modify the import and export packages of the bundle pom files as the classes will be generated into Java packages that should already be correctly configured in the standard pom files. If you deviate from those standards you need to manually ensure that the imports and export declarations in the maven bundle plugin configuration is correct. The code generation has known (and unknown) limitations of which most are described in this document. Regeneration of code is supported, most generated artifacts will get overwritten during this process. Therefore you should be careful when making modifications to the generated code. At this point we can only provide limited support for the code generation project and are in general happy to receive feedback, being it either bug reports or feature requests. But due to resource constraints we might not always be able to address either very quickly. 1.1 Change History Version 0.1 Release Date: Initial Version Version 0.3 Release Date: Bug fixes: 3

4 added configurable mobiliserversion parameter to maven plugin to handle different spring versions handling some more exception cases when Entity beans are passed as parameters in additional DAO methods writing correct privilege names into SQL file (from endpoint interface annotation) generating XSD documentation at correct position in XSD in case of non standard simple types fixed bug in converter when creating new bean with non-generated PK converter implemenation was not copying primary key when returning results from DB New features: Generation of DDL scripts for all supported databases (ASE, DB2, PostgreSQL, Oracle) from JPA beans! Renamed maven plugin from dao2svc to mobcodegen Added additional maven plugin goal xsd2ep (in same bundle) to generate Endpoint classes and configuration based on an XSD. 4

5 Chapter 2 DAO 2 Service The dao2svc code generation takes the Entity (JPA) beans and the DAO classes and generates all required components to provide (web) services on those. The generated services are generally not recommended for direct consumption by Smartphones because they provide raw access to the database - unless the generated classes are extended at the relevant and supported interfaces. Please read "Mobiliser_Platform_5.1_SmartPhone_Service_Development.pdf" to understand the pitfalls of developing services that are meant for consumption from the Internet. 2.1 Configuration Changes Most data for the code generation is retrieved via Java reflection from the classes and existing Java Annotations for the JPA beans. To get some further information that is required to render meaningful data we had to introduce a couple of new Annotations that have to be used on the Entity beans and DAO classes. These Annotation have a retention of type RUNTIME, therefore you will also need to not only add the dependency to the projects/modules in the persistence modules but the bundle with the Annotations also needs to be added to the OSGi container bundle repository by modifying the assembly. This dependency needs to be added to the Maven module that contains the JPA beans, in the standard template this is the "persistence" module. 2 < dependency > 3 < groupid > com. sybase365. mobiliser. util. codegen </ groupid > 4 < artifactid > com. sybase365. mobiliser. util. codegen. annotations </ artifactid > 5 < version > 0.3 </ version > 6 </ dependency > 7... Listing 2.1: Dependency for the new Annotations in the pom.xml file The same dependency also needs to be added to the "dist" module (dist/pom.xml). The maven plugin for the code generation can be added to any module, but the preferred place is to add it into the module that contains the DAO interfaces and the DAO factory, in the standard template this is the "persistence" module. 2 < plugin > 3 < groupid > com. sybase365. mobiliser. util. codegen </ groupid > 4 < artifactid > mobcodegen - maven - plugin </ artifactid > 5 < version > 0.3 </ version > 6 < configuration > 5

6 7 < daofactoryinterface > com. sybase365. mobiliser. custom. project. persistence. dao. factory. api. DaoFactory </ daofactoryinterface > 8 < projectname > custom. project </ projectname > 9 < modulename > dummy </ modulename > 10 </ configuration > 11 </ plugin > Listing 2.2: Dependency for the new Annotations in the pom.xml file The example above also shows the three required configuration parameters. Please run a mvn help:describe -Dplugin=mobcodegen -Ddetail to get a description of the required and optional parameters. The parameters should be changed to match your project. Additionally you need to make changes to the assembly instructions in the dist module to make sure that the bundle containing the plugins is added to the container bundle repository. The file is located in dist/src/- main/assembly/dist.xml 2 < fileset > 3 < directory > target / classes / bundles </ directory > 4 < outputdirectory >/ money / bundles /10 - mobiliser - persistence </ outputdirectory > 5 < filemode > 0644 </ filemode > 6 < includes > 7 < include > com. sybase365. mobiliser. util. codegen. annotations * </ include > 8 </ includes > 9 </ fileset > Listing 2.3: Add Annotations as fileset in the assembly You may encounter missing dependencies/class loader issues when the plug in was uploaded to the maven repository without using the included pom.xml. In this case, please add the plug in dependency as follows: 2 < plugin > 3 < groupid > com. sybase365. mobiliser. util. codegen </ groupid > 4 < artifactid > mobcodegen - maven - plugin </ artifactid > 5 < version > 0.3 </ version > 6 < dependencies > 7 < dependency > 8 < groupid > org. springframework </ groupid > 9 < artifactid > org. springframework. core </ artifactid > 10 < version > RELEASE </ version > 11 </ dependency > 12 </ dependencies > 13 < configuration > 14 < daofactoryinterface > com. sybase365. mobiliser. custom. project. persistence. dao. factory. api. DaoFactory </ daofactoryinterface > 15 < projectname > custom. project </ projectname > 16 < modulename > dummy </ modulename > 17 </ configuration > </ plugin > Listing 2.4: Dependency for the new Annotations in the pom.xml file 6

7 2.2 Java Code The code generation always starts with the DAO Factory. All get*dao() methods are assumed to return DAO interfaces that provide access to a JPA bean. For each JPA bean that is found the CRUD operations will be created automatically. In addition operations will be created for each method in the DAO interface that has annotation JPA Beans If the existing JPA beans comply to the conventions that are defined in the Mobiliser developer guide you can use them right away for the code generation. The JPA beans should be extended annotations on class and field level to have some documentation created in the XSD contracts. ( name = " CUS_BLACKLIST ") ( name = " id ", column ( name = " ID_ENTITY ")) (" This bean keeps track of all black lists ") 6 public class Blacklist extends GeneratedIdEntry { 7 8 /** The blacklist type - no mapping for lookup tables. */ ( optional = false ) ManyToOne ( fetch = FetchType. LAZY, optional = false ) JoinColumn ( name = " ID_ BLACKLIST_ TYPE ", nullable = false ) (" This is a lookup value - the types can be freely defined ") 13 private BlacklistType blacklisttype ; /** The name of the blacklisted person. */ ( optional = true ) ( name = " STR_ NAME ", nullable = false, length = LENGTH_ STRING_ LARGE ) (" The name for this blacklist entry ") 19 private String name ; Listing 2.5: JPA Bean annotations Please make sure that you always provide the optional parameters nullable and for Strings length, for int/long precision and for float/double precision and scale in annotation. Also the handling of booleans should strictly follow the conventions defined in "Mobiliser_Framework_5.0_Development_Guide.pdf". Known relationships are not mapped in the XSD contract at relationships are rendered in the XSD contracts but instead of a nested bean only the primary key of the bean is added to the contract. Composite primary keys are not supported DAO Interfaces In case you want to expose additional methods (beyond CRUD) from the DAO interface as operations in the contract you need to annotate them specifically. MobiliserService ( description = " Loads a list of Blacklists by name ", privilege = " BL_FOR_NAME ") 3 List < Blacklist > getblacklistsforname ( 7

8 MobiliserParam ( name = " name ", required = true, length = 80, description = " the name of the customer to search ") String name, MobiliserParam ( name = " blacklisttype ", required = false, description = " the optional type of the blacklist to filter for ") Integer blacklisttype ); 6... Listing 2.6: JPA Bean annotations Any method annotated also must have annotation at each parameter. The privilege parameter in annotation will be used as the required privilege for the service call (SQL inserts will also be generated). The privilege name will always be prefixed with "WS_". All other annotation parameters should be self explanatory. The description of the method and the parameters is optional but it is highly recommended to provide it. Known limitations: complex types (beans) that are not included in the JPA beans accessible through the DAO factory are not supported 2.3 Code Generation All JPA beans and DAO classes should be freshly compiled before each code generation. To generate the code go to the directory that contains the plugin configuration (2.4) and execute the following command: mvn compile mobcodegen:dao2svc In case of success you will see some log out put regarding the generated classes. If the class names or locations do not match the expected values, please consult the maven plugin documentation (mvn help:describe -Dplugin=mobcodegen -Ddetail). In case of success the following files should have been created:../services/contract/src/main/resources/com/sybase365/mobiliser/custom/project/services/contract/xsd/dummybeans-1-0.xsd For each JPA bean a corresponding complextype is created in this XSD file.../services/contract/src/main/resources/com/sybase365/mobiliser/custom/project/services/contract/xsd/dummyrequests-1-0.xsd The CRUD operations plus the annotated DAO methods are created as complextypes and elements.../services/contract/src/main/java/com/sybase365/mobiliser/custom/project/services/contract/api/idummyendpoint.java The Java endpoint interface which contains all operations that are also available in the xsd.../services/endpoint/src/main/java/com/sybase365/mobiliser/custom/project/services/endpoint/abstractdummyendpoint.ja This is the implementation of the endpoint interface. It mainly forwards all service calls to the business logic. The class is abstract and is extended by the next class../services/endpoint/src/main/java/com/sybase365/mobiliser/custom/project/services/endpoint/dummyendpoint.java This class is empty when generated and extends the abstract endpoint implementation. The file will not get overwritten if it already exists. You can overwrite any of the methods from the abstract class in this class to modify the behavior.../services/endpoint/src/main/resources/meta-inf/spring/bundle-context-dummy.xml This is the required spring configuration for the endpoint. Please note that it is assumed that the callerutils and txadvice are already available in the spring context. This is the case in the standard customisation project setup. 8

9 ../businesslogic/api/src/main/java/com/sybase365/mobiliser/custom/project/converter/idummyconverter.java The Java interface for the converter which transforms the contract beans to the JPS bean and back.../businesslogic/impl/src/main/java/com/sybase365/mobiliser/custom/project/converter/impl/abstractdummyconverter.jav The implementation of the converter interface. Copies all fields between the beans. The class is abstract.../businesslogic/impl/src/main/java/com/sybase365/mobiliser/custom/project/converter/impl/dummyconverter.java This class is empty when newly generated and extends the abstract converter implementation. This file will not get overwritten if it already exists. You can overwrite any of the methods from the abstract class to modify the behavior.../businesslogic/api/src/main/java/com/sybase365/mobiliser/custom/project/businesslogic/idummylogic.java The Java interface for the business logic methods.../businesslogic/impl/src/main/java/com/sybase365/mobiliser/custom/project/businesslogic/impl/abstractdummylogic.java The implementation of the business logic interface. Just forwards each call to the underlying DAO interface. This class is abstract.../businesslogic/impl/src/main/java/com/sybase365/mobiliser/custom/project/businesslogic/impl/dummylogic.java This class is empty when newly generated and extends the abstract businesslogic implementation. This file will not get overwritten if it already exists. You can overwrite any of the methods from the abstract class to modify the behavior and add some "real" logic. The delete operations must be overwritten as the standard implementation will throw an Exception when being called.../businesslogic/impl/src/main/resources/meta-inf/spring/bundle-context-dummy.xml This is the required spring configuration for the businesslogic and the converter implementations. Please note that it is assumed that the daofactory and moneydaofactory are already available in the spring context. This is the case in the standard customisation project setup.../persistence/src/main/schema/scripts/common/002_data/xxx_dummy_svc_privs.sql Contains INSERT statements for the newly created services. The file needs to be renamed (you can also overwrite the standard name in the maven plugin configuration). But this needs to be handled carefully, because files with a new timestamp (after regeneration) will cause issues with dbmaintain. You might need to manually handle the content of this file and merge it with existing SQL files or create a new one out of it. If everything was created correctly you can re-build the full project and launch the new container to access the services! Make sure to also execute the created SQL scripts, otherwise you will ge tan HTTP 403 error because no user will have the required privileges. 9

10 Chapter 3 XSD 2 Endpoint The xsd2ep maven plugin goal takes an existing XSD file with RequestTypes and ResponseTypes (defined as complextypes) and create the required endpoint classes and configuration. The endpoint implementation methods are created as stubs and just return an empty response when being called. This is a good starting point if you want to create complexer services (not CRUD type) and/or services for public consumption (e.g. Smartphone). Note: In this kind of code generation it is much more likely that you are going to make modifications to the generated classes and configuration. A re-generation will overwrite most classes without user confirmation! Please make sure that you commit your changes to the source code repository so that you can restore them in case you accidentally overwrote the files. 3.1 Configuration Changes There are no new runtime dependencies been introduced for the generated code. The maven plugin for the code generation can be added to any module, but the preferred place is to add it into the module that contains the service contract definition (services/contract). All required XSDs must be available in the classpath. 2 < plugin > 3 < groupid > com. sybase365. mobiliser. util. codegen </ groupid > 4 < artifactid > mobcodegen - maven - plugin </ artifactid > 5 < version > 0.3 </ version > 6 < dependencies > 7 < dependency > 8 < groupid > org. springframework </ groupid > 9 < artifactid > org. springframework. core </ artifactid > 10 < version > RELEASE </ version > 11 </ dependency > 12 </ dependencies > 13 < configuration > 14 < xsdrequestsresource > com / sybase365 / mobiliser / custom / project / services / contract / xsd / spm - requests xsd </ xsdrequestsresource > 15 < projectname > custom. project </ projectname > 16 < modulename > spm </ modulename > 17 < mobiliserversion > 5.1 </ mobiliserversion > 18 </ configuration > 19 </ plugin >

11 Listing 3.1: Dependency for the new Annotations in the pom.xml file The example above also shows the three required configuration parameters (mobiliserversion is optional). Please run a mvn help:describe -Dplugin=mobcodegen -Ddetail to get a description of the required and optional parameters. The parameters should be changed to match your project. 3.2 XSD All your operation/methods/services need to be defined as complextypes in the XSD. Per convention the business objects are defined in an XSD that has the word "beans" in its name. The actual requests and responses that use the beans are defined in an XSD file that has "requests" in its name. This is the one that needs to be referred to in the pom.xml puglin configuration. Please see section "5.3 Contract" in "Mobiliser_ Framework_5.0_Development_Guide.pdf" for details regarding the creation of the XSD contract (you can ignore the comment about creating an additional Request/Response element for each RequestType/ResponseType complextype - these are generated by the maven plugin). The plugin will scan the XSD for all complextypes that have a name ending either with "RequestType" or "ResponseType". The missing elements are added to the XSD automatically and do not need to be created manually. You can have additional Request and Response elements in the XSD, those will not be touched. There will be no elements created for abstract complextypes. After the missing elements have been created, the XSD is scanned again and the list of operations (methods) is determined based on the presence of elements whose name ends with Request and that have a corresponding Response element. This list of operations is used to create the Java interface which is usually part of the contract bundle. The privileges are rendered based on the name of the operation. The privileges are added to the service call and an SQL script is generated that contains the privileges. As the next step the endpoint class is created which is the implementation of the previously generated Java interface. Along with this class the required Spring configuration is created to expose the service endpoint internally and externally. Finally some imports are added to the bundle plugin configuration of the pom.xml to ensure that all the required XSDs and the corresponding Java beans are available (direct imports as well as transitive imports). 3.3 Code Generation To generate the code go to the directory that contains the plugin configuration (3.1) - usually services/contract - and execute the following command: mvn compile mobcodegen:xsd2ep In case of success you will see some log out put regarding the generated classes. If the class names or locations do not match the expected values, please consult the maven plugin documentation (mvn help:describe -Dplugin=mobcodegen -Ddetail). In case of success the following files should have been created:../../services/contract/src/main/java/com/sybase365/mobiliser/custom/project/services/contract/api/ispmendpoint.java The Java endpoint interface which contains all operations that are also available in the xsd. If you are deploying the services for consumption over the Internet you need to change the interface and replace the RolesAllowed with PreAuthorize annotations to enforce cookie based authentication. Please see "Mobiliser_Platform_5.1_SmartPhone_Service_Development.pdf" for details. Please note that this file will get overwritten if you restart the code generation!../../persistence/src/main/schema/scripts/common/002_data/xxx_spm_svc_privs.sql 11

12 Contains INSERT statements for the newly created services. The file needs to be renamed (you can also overwrite the standard name in the maven plugin configuration). But this needs to be handled carefully, because files with a new timestamp (after regeneration) will cause issues with dbmaintain. You might need to manually handle the content of this file and merge it with existing SQL files or create a new one out of it.../../services/endpoint/src/main/java/com/sybase365/mobiliser/custom/project/services/endpoint/spmendpoint.java This is the implementation of the endpoint interface. The methods just all return an empty response. The file will not get overwritten if it already exists. The service implementation will need to go into here.../../services/endpoint/src/main/resources/meta-inf/spring/bundle-context-spm.xml This is the required spring configuration for the endpoint. Please note that it is assumed that the callerutils and txadvice are already available in the spring context. This is the case in the standard customisation project setup. Your endpoint implementation most likely needs more services from the OSGi registry otherwise you will not be able to implement any meaningful code. So you need to modify the file to pick additional services (existing or new) and inject it into your endpoint class. Please note that this file will get overwritten if you restart the code generation!../../services/endpoint/pom.xml The addtional import packages required to access the direct and transitive XSDs are added to the maven bundle plugin. If everything was created correctly you can re-build the full project and launch the new container to access the services! Make sure to also execute the created SQL scripts, otherwise you will ge tan HTTP 403 error because no user will have the required privileges. 12