How to build a cloud adapter

AMIS Conference Beyond the Horizon

Maarten Smeets

How to build a Cloud Adapter

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

http://javaoraclesoa.blogspot.com/

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

Introduction

4

5

What is a Cloud Adapter?On the outside

6

What is a Cloud Adapter?On the inside

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

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

Why build a Cloud AdapterA single solution for SOA, SB, ICS

• Build once deploy many!The same Cloud Adapter on– SOA Suite– Service Bus– Integration Cloud Service

10

Why build a Cloud AdapterSales and Marketing

• Sell it in the Marketplace and promote your company

12

Why build a Cloud AdapterMove workload to the citizen developer

Move workload from your developers to your business users. Configure, not code. Increase business agility!

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!

14

Getting started

15

16

Getting startedCloud Adapter Development Lifecycle

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.htmlhttp://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 AgentUndocumented but similar

Allows developing and testing in JDeveloper (designtime) andIntegrated WebLogic Server (runtime)

Allows testing designtime and runtime in Integration Cloud Service

https://beehiveonline.oracle.com/teamcollab/library/Oracle/Cloud_Adapter_DevKit/



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

18

Set-up a runtime environmentPatching 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)\Java\jdk1.7.0_79“set PATH="C:\Program Files (x86)\Java\jdk1.7.0_79\bin";%PATH%set ORACLE_HOME=C:\Oracle\Middleware1213\Oracle_Home(in the patch directories, e.g. p19707784_121300_Generic\19707784)%ORACLE_HOME%\OPatch\opatch 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)\Java\jdk1.7.0_79\bin\java.exe" -i GUI

• For Windows: Mind the file permissions!

19

Set-up a JDeveloper projectInclude the libraries

• Import the Cloud Adapter SDK JAR files

20

Set-up a JDeveloper projectExtension 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!

21

Set-up a JDeveloper projectMANIFEST.MF

• Update your MANIFEST.MF with the required Cloud Adapter OSGi modules

• Create a JAR deployment profileMake sure the MANIFEST.MF is included

22

Set-up JDeveloperHow 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

23

Use the Cloud Adapter in JDeveloper

Composite service or reference Service Bus proxy or business service

24

Use the Cloud Adapter in JDeveloper

25

Set-up a runtime environmentICS 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

26


• 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 adapterUpdate [ICSExecutionAgentHome]/ICSOP/data/user_projects/domains/compact_domain/bin/setDomainEnv.sh

• To avoid NumberFormatExceptions update the proxy settings in [ICSExecutionAgentHome]/ICSOP/data/user_projects/domains/compact_domain/bin/setICSDomainEnv.sh

27


28


29


The Cloud Adapter SDK

30

31

The Cloud Adapter SDKWhat 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

32

Usual Cloud Adapter package structure

runtime

designtime

metadata

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

34

cloud-adapter.xml

UI provider class

Security policies

Interaction patterns

Adapter factory class

Adapter propertiesWill end up in .jca file

35

The Cloud Adapter SDKDesigntime model

Creates JCA and integration WSDL

Called in the UIBinding classmethod generateMetadataArtifacts

Parsers for REST and WSDL are available

Created on the welcome pageUsed on operations page

36

DesigntimeCloudAdapterUIBinding

• 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 / descriptionWelcome pageCloudAdapterWelcomePage

Connection pageCloudAdapterConnectionPage

Operations pageCloudAdapterOperationsPage

Request / response pageICloudAdapterPage

SummarySummary pageCloudAdapterSummaryPage

37

DesigntimeUnifiedUI

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

38

The Cloud Adapter SDKRuntime model

Artif

act

sRu

ntim

e cl

asse

sTa

rget

ap

plic

atio

n

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

40

The Cloud Adapter SDKAdvanced features: Batch and Bulk

41

The Cloud Adapter SDKAdvanced 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

42

Tips and tricksCommon 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 exceptionIn 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)

43

Tips and tricksDetermine 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

Questions

@MaartenSmeetsNL

https://nl.linkedin.com/in/smeetsm

Download sample code athttps://github.com/MaartenSmeets/cloudadapter

45