In this presentation I will show you what is needed to build your own Cloud Adapter using the Cloud Adapter SDK. The architecture of the adapter framework will be explained and also the required steps to allow others to use your adapter from the Oracle Marketplace will be shown. The custom adapter which has been created as a sample implementation is a Z-Wave-Adapter which can be used to allow easy integration with devices using the Z-Wave protocol (such as sensors which can be used for home automation). The usage of the adapter in real life will also be demonstrated.

1. AMIS Conference Beyond the Horizon
Maarten Smeets
How to build a Cloud Adapter

2. Introduction
• About AMIS
– Located in the Netherlands
• About me
– Oracle Integration Consultant
– Experience with Oracle SOA Suite since 2007
– Well certified (SOA, BPM, Java, SQL,
PL/SQL among others)
– Author of more than 100 blog articles
(http://javaoraclesoa.blogspot.com)
@MaartenSmeetsNL
https://nl.linkedin.com/in/smeetsm

3. 3
Agenda
• Introduction
– What is a Cloud Adapter
– Why build a Cloud Adapter
– Why not build a Cloud Adapter
• Develop a Cloud Adapter. Getting started
– Setting up your development environment
– Setting up your JDeveloper / SOA / ServiceBus environment
– Setting up your ICS environment
• The Cloud Adapter SDK
– Designtime components
– Runtime components
– Tips and tricks
• End to end demonstration

4. Introduction
4

5. 5
What is a Cloud Adapter?
On the outside

6. 6
What is a Cloud Adapter?
On the inside

7. 7
What is a Cloud Adapter?
Designtime
• A Cloud Adapter provides designtime JDeveloper and ICS wizards to make it easy for a (citizen) developer to
connect to complex services such as Salesforce, Oracle Sales Cloud, Google Calendar, Many others
Integration Cloud Service JDeveloper

8. 8
What is a Cloud Adapter?
Difference between Technology and Cloud Adapter
Technology Adapter Cloud Adapter
Packaging RAR file JAR file
Description files ra.xml extention.xml + cloud-adapter.xml
Configuration Application + AS Application
Target audience Developers Citizen developers + Developers
Integration Cloud Service
Service Bus
Composites

9. 9
Why build a Cloud Adapter
A single solution for SOA, SB, ICS
• Build once deploy many!
The same Cloud Adapter on
– SOA Suite
– Service Bus
– Integration Cloud Service

10. 10
Why build a Cloud Adapter
Sales and Marketing
• Sell it in the Marketplace
and promote your company

11. 12
Why build a Cloud Adapter
Move workload to the citizen developer
Move workload from your developers to your business users. Configure, not code. Increase business agility!

12. 13
Why not build a Cloud Adapter?
• Development is not easy. Do your developers have the required skills?
Most likely you will not be done within 2 months. There is very little information and/or documentation.
– Getting to know the SDK
What is provided and how can you use it? What do you need to build yourself
– Jdeveloper extension development
How to efficiently develop and debug
– Designtime/runtime requirements
How to make the adapter available for usage
• You are not planning to sell the adapter in the Marketplace
– ROI takes longer
• You do not require citizen developers to configure integrations in ICS
– Developers will have less benefit of a Cloud Adapter. A custom integration might be more cost effective
• You can wait until someone else has developed it. Check with Oracle which adapters are on the roadmap!

13. 14

14. Getting started
15

15. 16
Getting started
Cloud Adapter Development Lifecycle

16. 17
How to get started?
• Obtain the Cloud Adapter SDK
– https://beehiveonline.oracle.com/teamcollab/library/Oracle/Cloud_Adapter_DevKit/
• Set-up your test environment / runtime
– Set-up your Service Bus / SOA environment
http://niallcblogs.blogspot.nl/2015/06/408-first-steps-with-cloud-adapter-sdk.html
http://ninckblokje.github.io/2016/03/15/cloud-adapter-sdk-part1.html
• Set-up a JDeveloper project (use 12.1.3 for ICS)
– Described in the Cloud Adapter SDK documentation
• Set-up your ICS test environment. Use the ICS Execution Agent
Undocumented but similar
Allows developing and testing
in JDeveloper (designtime) and
Integrated WebLogic Server (runtime)
Allows testing designtime and
runtime in Integration Cloud Service

17. 18
Set-up a runtime environment
Patching a SOA Suite / Service Bus installation
• Required files:
– fmw_12.1.3.0.0_soaqs_Disk1_1of1.zip
– ofm_adapters_application_generic_12.1.3.0.0_disk1_1of2.zip
– ofm_adapters_application_generic_12.1.3.0.0_disk1_2of2.zip
– fmw_12.1.3.0.1_cloud_adapters_Disk1_1of1.zip (patches)
• For Windows: fmw_12.1.3.0.1_cloud_adapters_Disk1_1of1.zip
– Use a 32 bit 1.7 JDK and of course replace the relevant parts below
set JAVA_HOME="C:Program Files (x86)Javajdk1.7.0_79“
set PATH="C:Program Files (x86)Javajdk1.7.0_79bin";%PATH%
set ORACLE_HOME=C:OracleMiddleware1213Oracle_Home
(in the patch directories, e.g. p19707784_121300_Generic19707784)
%ORACLE_HOME%OPatchopatch apply
• For Windows: you can start the ofm_adapters_application_generic_12.1.3.0.0 installer with:
– iwora12c_application-adapters_win.exe LAX_VM "C:Program Files (x86)Javajdk1.7.0_79binjava.exe" -i GUI
• For Windows: Mind the file permissions!

18. 19
Set-up a JDeveloper project
Include the libraries
• Import the Cloud Adapter SDK JAR files

19. 20
Set-up a JDeveloper project
Extension development + JDK 1.7
• Make sure the feature Extension Development is enabled. Makes debugging easy!
• Set the JDK to 1.7. ICS is still WebLogic 12.1.3!

20. 21
Set-up a JDeveloper project
MANIFEST.MF
• Update your MANIFEST.MF with the required Cloud Adapter OSGi modules
• Create a JAR deployment profile
Make sure the MANIFEST.MF is included

21. 22
Set-up JDeveloper
How to use your custom adapter?
• Setup designtime
– Copy the Cloud Adapter to
[JDEV_HOME]/jdeveloper/dropins folder
• Setup runtime
– Copy the Cloud Adapter to
[JDEV_HOME]/soa/soa/modules/oracle.cloud.adapter_12.1.3
– Edit setDomainEnv of your embedded WebLogic server
update the POST_CLASSPATH to include the Cloud Adapter JAR file


22. 23
Use the Cloud Adapter in JDeveloper
Composite service or reference Service Bus proxy or business service

23. 24
Use the Cloud Adapter in JDeveloper

24. 25
Set-up a runtime environment
ICS Execution Agent
• Make sure you have an ICS account (trial is sufficient). Required for Execution Agent installation
• Download and install the ICS Execution Agent (Oracle Enterprise Linux 6 UC4 or above)
https://docs.oracle.com/cloud/latest/intcs_gs/ICSUG/GUID-AFE5B4E2-2DEF-4BC2-8F9C-6B214BF7B56D.htm

25. 26
Set-up a runtime environment
ICS Execution Agent
• Add the custom cloud adapter JAR file to
[ICSExecutionAgentHome]/ICSOP/app/Oracle/Middleware/Oracle_Home/soa/soa/modules/oracle.cloud.adapter_12.1.3
• Add a POST_CLASSPATH entry for the custom cloud adapter
Update [ICSExecutionAgentHome]/ICSOP/data/user_projects/domains/compact_domain/bin/setDomainEnv.sh

26. • To avoid NumberFormatExceptions update the proxy settings in
[ICSExecutionAgentHome]/ICSOP/data/user_projects/domains/compact_domain/bin/setICSDomainEnv.sh
27
Set-up a runtime environment
ICS Execution Agent

27. 28
Set-up a runtime environment
ICS Execution Agent

28. 29
Set-up a runtime environment
ICS Execution Agent

29. The Cloud Adapter SDK
30

30. 31
The Cloud Adapter SDK
What does it help you do?
Designtime (DT) components
• Single implementation for wizards
• Provides defaults for all pages
• Process remote artifacts (WSDL’s)
• Produce runtime artifacts
Runtime (RT) components
• Consume runtime artifacts
• Invokes by JCA framework
• Security, batching,
connection management, etc

31. 32
Usual Cloud Adapter package structure
runtime
designtime
metadata

32. 33
extension.xml
SOA/BPM adapter configuration
ICS/Service Bus adapter configuration
Resource bundle for placeholders
Endpoint implementation class
Endpoint implementation class
Binding
properties
Description

33. 34
cloud-adapter.xml
UI provider class
Security policies
Interaction patterns
Adapter factory class
Adapter properties
Will end up in .jca file

34. 35
The Cloud Adapter SDK
Designtime model
Creates JCA and
integration WSDL
Called in the UIBinding class
method generateMetadataArtifacts
Parsers for REST and WSDL
are available
Created on the welcome page
Used on operations page

35. 36
Designtime
CloudAdapterUIBinding
• Interaction between wizard and adapter pages
• Determines pages displayed and creates page
instances
– Small differences between ICS and Jdeveloper. E.g.
connection page in ICS cannot be skipped Connection
Operation
Request / response
Name / description
Welcome page
CloudAdapterWelcomePage
Connection page
CloudAdapterConnectionPage
Operations page
CloudAdapterOperationsPage
Request / response page
ICloudAdapterPage
Summary
Summary page
CloudAdapterSummaryPage

36. 37
Designtime
UnifiedUI
UnifiedUI provides one way
to code your UI for Jdeveloper
wizards, ICS, Service Bus
It provides classes like:
• EditField
• ButtonObject
• SelectItem
• ShuttleObject
These classes are well
documented in JavaDoc

37. 38
The Cloud Adapter SDK
Runtime modelArtifactsRuntimeclassesTarget
application
Cloud Application
Configuration file
Integration WSDL
Endpoint
WSDL / REST
RuntimeConnectionFactory
(CloudApplicationConnectionFactory)
CloudConnection
(CloudConnector)
MessageReceiver
(CloudMessageReceiver)
Connection
(AbstractCloudApplicationConnection)
MessageHandler
(CloudMessageHandler)
Target Application
Endpoint activation
Mapping to target format
Inbound
Outbound
RuntimeFactory
Invokes

38. 40
The Cloud Adapter SDK
Advanced features: Batch and Bulk

39. 41
The Cloud Adapter SDK
Advanced features: Metadata downloading and caching
Downloading of remote dynamic artifacts can be slow
due to the remote applications logic e.g. Oracle RightNow
In ICS the adapter instance is shared. Downloading and
processing of remote metadata can be improved by caching

40. 42
Tips and tricks
Common Issues
• I cannot see my adapter in JDeveloper
– Have you correctly installed (all parts of) the Cloud Adapter SDK?
– Is the extension.xml file in the correct location in the JAR file?
– Does the extension.xml indicate the correct category for the Adapter
– Are the file permissions for the JAR file set correctly?
• At runtime my adapter gives a class not found exception
In the ICS wizard I cannot see my adapter
– Make sure the Adapter is in the POST_CLASSPATH in setDomainEnv
• I cannot obtain an instance of my MetadataBrowser
– Did you override the method which used to create the MetadataBrowser?
– Are all the required Context variables set? (undocumented, look at the Cloud SDK code)

41. 43
Tips and tricks
Determine in which JAR a class is
• Open the declaration of an SDK class. When asked, generate a stub in JDeveloper JAR location
This is just a generated stub

42. Questions
@MaartenSmeetsNL
https://nl.linkedin.com/in/smeetsm
Download sample code at
https://github.com/MaartenSmeets/cloudadapter

43. 45