soadomain: Oracle Service Bus - Tutorial 1: Routing a Loan Application

El objetivo de este tutorial es revisar uno de los ejemplos que vienen en la instalación de Oracle Service Bus. Específicamente se revisará el tutorial 1 Routing a Loan Application. En la documentación oficial de oracle este ejemplo se revisa usando el entorno gráfico que provee la consola del OSB, pero aquí se verá usando Eclipse OEPE.

Antes de poder desarrollar este tutorial es necesario haber creado un dominio weblogic para OSB.

El servicio que se desea crear hará uso de 2 webservices externos. Como estamos en un entorno de desarrollo estos webservices se deployarán en el mismo dominio WebLogic donde está instalado el OSB.

Estas son las secciones que componen el tutorial:

1. Deploy de los webservices externos
2. Revisión de los XML usados por los webservices
3. Pseudocódigo del servicio OSB
4. Creación del Proyecto OSB en Eclipse
5. Deploy del proyecto en el servidor OSB
6. Probando nuestro servicio OSB

Deploy de los webservices externos

1. Identificar archivos .jar: en la siguiente ruta hay 4 archivos .jar:

C:\Oracle\OracleServiceBus\Oracle_OSB1\samples\servicebus\examples\build\webservices

creditLoan_jws_basic_ejb.jar
largeLoan_jws_basic_ejb.jar
manager_jws_basic_ejb.jar
normalLoan_jws_basic_ejb.jar

Estos archivos representan a 4 webservices de los cuales se usarán 2 en este tutorial: el manager y el normal.

2. Conectarse a la consola de administración de WebLogic
http://soadev:7001/console

Click en Deployments.
Click Install.

3. En el Path colocar la ruta de los archivos
Path: C:\Oracle\OracleServiceBus\Oracle_OSB1\samples\servicebus\examples\build\webservices

Seleccionar uno de los archivos .jar. Click Next, Next, Finish. Repetir para los otros 3 archivos.

Revisión de los XML usados por los webservices

Una vez deployados los webservices se pueden probar con soapUI, para revisar los XML de input y output que utilizan.

Servicio NormalLoanApprovalService

URL WSDL
http://soadev:7001/njws_basic_ejb/NormalSimpleBean?WSDL

XML Input Ejemplo
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:exam="http://example.org">
 <soapenv:Header/>
 <soapenv:Body>
 <exam:processLoanApp soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <loanRequest xsi:type="java:LoanStruct" xmlns:java="java:normal.client">
 <Name xsi:type="xsd:string">Smith</Name>
 <SSN xsi:type="xsd:string">1234567</SSN>
 <Rate xsi:type="xsd:double">5.3</Rate>
 <Amount xsi:type="xsd:long">9000000</Amount>
 <NumOfYear xsi:type="xsd:string">10</NumOfYear>
 <Notes xsi:type="xsd:string">Manager Loan Application Review Service</Notes>
 </loanRequest>
 </exam:processLoanApp>
 </soapenv:Body>
</soapenv:Envelope>

XML Output Ejemplo
<env:Envelope env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header/>
 <env:Body>
 <m:processLoanAppResponse xmlns:m="http://example.org">
 <return>
 <java:Name xmlns:java="java:normal.client">Smith</java:Name>
 <java:SSN xmlns:java="java:normal.client">1234567</java:SSN>
 <java:Rate xmlns:java="java:normal.client">5.3</java:Rate>
 <java:Amount xmlns:java="java:normal.client">9000000</java:Amount>
 <java:NumOfYear xmlns:java="java:normal.client">10</java:NumOfYear>
 <java:Notes xmlns:java="java:normal.client">APPROVED BY THE NORMAL LOAN APPLICATION PROCESSING SERVICE</java:Notes>
 </return>
 </m:processLoanAppResponse>
 </env:Body>
</env:Envelope>

Fijarse que en el campo <Notes> se detalla que fue aprobado por el servicio Normal.

Servicio ManagerApprovalService

URL WSDL
http://soadev:7001/mjws_basic_ejb/ManagerSimpleBean?WSDL

El formato XML de input/output es idéntico al webservice anterior. Sólo se diferencia porque en el elemento <Notes> de la respuesta se puede ver "APPROVED BY THE MANAGER...".

Pseudocódigo del servicio OSB

El servicio a crear también será un webservice, es decir, tendrá una URL WSDL que podrá ser usada por otras aplicaciones para invocarlo. El formato XML de input/output será el mismo de los webservices revisados.

Nuestro servicio OSB debe validar el parámetro de entrada <Rate> y según su valor, invocar al webservice NormalLoan o al webservice ManagerApproval. Como ambos webservices usan el mismo formato de XML no es necesario realizar transformaciones.

Este es el pseudocódigo:

CREATE SERVICE LoanGateway1 (/processLoanApp/loanRequest)
RETURN </processLoanAppResponse/return>
BEGIN
 IF( /processLoanApp/loanRequest/Rate < 5) THEN
 CALL ManagerApprovalService(/processLoanApp/loanRequest);
 ELSE
 CALL NormalLoanApprovalService(/processLoanApp/loanRequest);
 END IF;
END SERVICE LoanGateway1;

Creación del Proyecto OSB en Eclipse

1. Crear un proyecto de configuración OSB

Un proyecto de configuración OSB se usa para almacenar la información de configuración que se usará en un dominio OSB. Se puede pensar que un proyecto de configuración es como una representación de un dominio OSB. Cuando se deployan proyectos a un dominio no se hacen individualmente, lo que se deploya al OSB es un proyecto de configuración OSB.

Se crea de la siguiente manera:

- Botón derecho en Project Explorer > New > Oracle Service Bus Configuration Project
- Nombre: OSB_Tutoriales
- El resto de los parámetros se dejan con el valor default.
- Click Finish.

2. Crear un nuevo proyecto OSB
Dentro del proyecto de configuración se crea un nuevo proyecto OSB:

- Botón derecho en OSB_Tutoriales > New > Oracle Service Bus Project
- Project name: MortgageBroker

- Dentro del proyecto MortgageBroker se crean 3 folders: WSDL, ProxyService, BusinessService (Botón derecho > New > Folder).

3. Creación del Proxy Service
- Botón derecho en el folder ProxyService > New Proxy Service.
- Filename: LoanGateway1
- Service Type: WSDL Web Service > Click Browse
- Click en Consume: para ir a buscar el archivo wsdl con la URL del webservice Normal. Se podría usar el WSDL del otro webservice (Manager) pero como tienen el mismo formato da igual.
- Service resource: URI
- URI: http://localhost:7001/njws_basic_ejb/NormalSimpleBean?WSDL
- Click en helloworld(port).
- En la ventana "Transport Configuration Change" click en Yes.

El wizard crea el archivo NormalSimpleBean.wsdl. Mover ese archivo al folder WSDL: Botón derecho en el archivo > Move... > WSDL

- En el Tab Transport: cambiar el Endpoint URI por: /loan/gateway1

4. Crear un Business Service para el webservice Normal
- Botón derecho en el folder BusinessService > New > Business Service
- File name: NormalLoan
- Click Finish.
- Service Type: WSDL Web Service > Click Browse
- Seleccionar el archivo NormalSimpleBean.wsdl
- Click en helloPort (port)
- Click OK.
- En la ventana "Transport Configuration Change" click en Yes.
- En el Tab Transport:
 - Protocol: http (es el default)
 - Load Balancing Algorithm: none (el balanceo de carga sólo es útil cuando se
 especifican múltilpes endpoints)
 - Endpoint URI: En la lista de Existing URIs sólo debería existir la siguiente URI:
http://localhost:7001/njws_basic_ejb/NormalSimpleBean
 Ese valor es el endpoint URI del webservice Normal deployado anteriormente.

5. Crear un Business Service para el webservice Manager
Este será el business service que se invocará cuando la tasa de interés de la solicitud de préstamo sea < 5%.

- Botón derecho en el folder BusinessService > New > Business Service
- File name: ManagerLoanReview
- Click Finish.
- Service Type: WSDL Web Service > Click Browse
- Click Consume
- Service resource: URI.
- URI: http://localhost:7001/mjws_basic_ejb/ManagerSimpleBean?WSDL
- Seleccionar helloPort, OK.
- En el Tab Transport: no es necesario modificar la URI, ya que debería ser la correcta.
- Load Balancing Algorithm: none

Mover el archivo ManagerSimpleBean.wsdl al folder WSDL: Botón derecho en el archivo > Move... > WSDL.

6. Agregando lógica al proxy service (configurando LoanGateway1)

Para meterle lógica a un proxy service se edita el tab Message Flows, colocando pipelines, stages, actions, etc.

- Botón derecho en LoanGateway1 > Insert Into > Route: Se crea el nodo RouteNode1.
- Botón derecho en RouteNode1: Insert Into > Communication > Routing Table
Una routing table se usa para la lógica del IF-ELSE.

Ahora vamos a agregar un IF:
- Click (o doble click) en el Routing Table.
- En la consola de Properties, click en <Expression>

- Se abre la ventana XQuery.
- En el Tab Variable Structure vamos a ir a buscar al parámetro Rate:
- Click en:
body > $body...(request) > processLoanApp > loanRequest > Rate
- Hacer drag&drop al Tab Expression. Debería mostrarse el valor:
$body/exam:processLoanApp/loanRequest/java:Rate
- Click OK.

Ahora agregamos el "< 5":
- Click en el "Case..."
- Operator : <
- Value : 5

Si se cumple el IF hay que invocar el webservice ManagerLoanReview. Para lograr esto:
- Click en el nodo Routing bajo el Case.
- En la consola Properties se hace click en Browse.
- Se levanta la ventana para seleccionar un servicio.
- Buscar el business service ManagerLoanReview.biz.
- En el campo Invoking: processLoanApp

Ahora agregamos el ELSE: invocar al webservice NormalLoan.
- Click en el nodo Routing debajo de Default.
- En la consola Properties:
Service : Buscar el business service NormalLoan.biz.
Invoking :processLoanApp

Deploy del proyecto en el servidor OSB

Se deployará el proyecto OSB_Tutoriales que contiene nuestro proyecto MortgageBroker. El deploy se hará a nuestro servidor local, pero el procedimiento que se seguirá también sirve para hacer el deploy a un servidor OSB remoto: primero se debe generar el .jar del proyecto y luego se deploya ese archivo a través de la consola del OSB.

1. Exportar el proyecto a un archivo .jar
- Botón derecho en OSB_Tutoriales > Export > Oracle Service Bus - Configuration jar
- Click en Browse: se selecciona la ruta: C:\SOA_Desarrollo\OSB_Tutoriales\
- Como nombre de archivo se elige: OSB_Tutoriales_export.jar
- Click Finish.

2. Importar archivo .jar al servidor OSB
- Conectarse a la consola OSB: http://soadev:7001/sbconsole
- En el menú de la izquierda seleccionar System Administration.
- Click en Create en el Change Center, para iniciar una nueva sesión.
- En Import Resources, click en Browse y seleccionar el archivo OSB_Tutoriales_export.jar
- Click Next > Import > Activate (en el Change Center).

- En la ventana que aparece al final, Activate Session, ingresar una descripción en el campo Description.

- Click en Submit.

Probando nuestro servicio OSB

Usando la Test Console

1. Conectarse a la consola del OSB: http://localhost:7001/sbconsole

2. En el menú de la izquierda: seleccionar Resource Browser > Service > Proxy Services

3. En la fila de LoanGateway1: click en el ícono del bichito, Launch Test Console.

NOTA: En algún momento me apareció el siguiente error:

Error Accessing Test Configuration
"Test Console" service is not running. Contact administrator to start this service.

Eso se debía a que la IP de mi equipo no era fija. Le configuré una IP fija y ahora funciona OK.

4. En el loanRequest copiar el siguiente código

<java:Name>Smith</java:Name>
<java:SSN>1234567</java:SSN>
<java:Rate>4.1</java:Rate>
<java:Amount>9000000</java:Amount>
<java:NumOfYear>10</java:NumOfYear>
<java:Notes>Manager Loan Application Review Service</java:Notes>
</loanRequest>

5.Click Execute: se puede ver la respuesta en Response Document. La respuesta indica que se ejecutó el servicio ManagerLoanReview porque la tasa de interés era < 5 (= 4.1). En Invocation Trace se puede ver el flujo de ejecución del proxy.

6. Hacemos una segunda prueba: pero con un Rate de 5.3. En este caso el servicio ejecutado fue NormalLoan.

Usando soapUI

La URL del webservice creado en OSB es:

http://soadev:7001/loan/gateway1?WSDL

Recordar que "/loan/gateway1" es el Endpoint URI que se configuró para el servicio.

Si creamos un nuevo proyecto en soapUI con esa URL, se puede generar un Request automáticamente. Se debe revisar el formato de los parámetros dentro de <loanRequest>. Si no se usa "java:" el servicio no realizará la correcta validación de <Rate>4.3</Rate> porque en nuestro código el proxy service usa la expresión:

$body/exam:processLoanApp/loanRequest/java:Rate

Por lo tanto, se debe modificar el Request generado por soapUI, agregando "java:" a los elementos.

Ejemplo de request:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:exam="http://example.org">
 <soapenv:Header/>
 <soapenv:Body>
 <exam:processLoanApp soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <loanRequest xsi:type="java:LoanStruct" xmlns:java="java:normal.client">
 <java:Name xsi:type="xsd:string">Smith</java:Name>
 <java:SSN xsi:type="xsd:string">1234567</java:SSN>
 <java:Rate xsi:type="xsd:double">4</java:Rate>
 <java:Amount xsi:type="xsd:long">9000000</java:Amount>
 <java:NumOfYear xsi:type="xsd:string">10</java:NumOfYear>
 <java:Notes xsi:type="xsd:string">Manager Loan Application Review Service</java:Notes>
 </loanRequest>
 </exam:processLoanApp>
 </soapenv:Body>
</soapenv:Envelope>

---
EOF
---

soadomain

martes, 20 de agosto de 2013

Oracle Service Bus - Tutorial 1: Routing a Loan Application