Follow Us on Twitter

Oracle ADF 12c EMG XML Data Control - koppel ADF-schermdata met het SOA-landschap

Januari 2016 - Voor het koppelen van data aan ADF-schermen kiezen organisaties verschillende oplossingen. In de praktijk kom je dan bijvoorbeeld de traditionele database tegen om data via ADF Business Components (ADFbc) te onderhouden. Weer andere klanten hebben een eigen SOA-landschap waarmee alle data gemanipuleerd kan worden en er zijn ook klanten die de twee oplossingen naast elkaar gebruiken.

In de praktijk wil je in het algemeen snel kunnen ontwikkelen om op een eenvoudige manier data te kunnen ontsluiten naar het scherm om deze data vervolgens weer op te slaan.

Er bestaat een opensource ADF EMG Extension die op betrekkelijk eenvoudige wijze het SOA-landschap kan gebruiken om alle data met ADF-schermen te kunnen onderhouden en dat is de ADF EMG XML Data Control.

Ik ga je uitleggen wat de ADF EMG XML Data Control is, wat deze extension kan door middel van een demo applicatie MyXmlDatacontrol en geef daarbij enkele tips om nog meer uit deze extension te halen.

ADF EMG XML Data Control

ADF EMG XML Data Control is een open source initiatief van de Enterprise Methodology Group (EMG). Het biedt een eenvoudige en declaratieve manier om een ADF Data Control te baseren op XML-bestanden, Web Services of Payloads. De ADF Data Controls worden o.a. gebruikt om data te koppelen aan pagina's.

Versie 1.0 werd vrijgegeven op Oracle Open World in september 2014. Er zijn inmiddels al verschillende bedrijven die de ADF EMG XML Data Control in hun productiecode hebben toegepast.

De XML Data Control is er in twee varianten, de variant voor JDeveloper 11g en de andere variant voor JDeveloper 12c. Als er eenmaal een ADF Data Control is geconfigureerd op basis van de XML Data Control dan is er voor de ontwikkelaar niets extra's meer nodig om direct aan de slag te gaan.

Voor meer detailinformatie kan je het volgende artikel lezen, Powerful and Easy ADF Data Control for XML Data van Richard Olrichs en Wilfred van der Deijl. Dit artikel geeft in vogelvlucht aan wat de plugin kan en hoe het in grote lijnen werkt.

Voorbeeld ADF Applicatie MyXmlDatacontrol

Ter ondersteuning van dit artikel heb ik een voorbeeld ADF-applicatie geschreven. Deze applicatie is gebouwd in JDeveloper 12c (12.1.2.0). Voordat je deze applicatie kunt gebruiken moet je twee ADF EMG Extensions installeren in JDeveloper. De voorbeeldapplicatie kan je hier downloaden.

Er bestaan twee versies van de XML Data Control, één versie voor JDeveloper 11g (11.1.1.x) en één versie voor 12c (12.1.2.x). Om de software in JDeveloper te kunnen gebruiken moet deze geïnstalleerd worden via Help | Check for updates. Kies vervolgens Official Oracle Extensions and Updates en klik Next. Kies op het volgende scherm ADF EMG Extension: XML Data Control en de ADF EMG Task Flow Tester en klik Finish om deze software te downloaden en te installeren in JDeveloper. Om alle software goed te laten werken moet je JDeveloper even herstarten.

Overzicht van te installeren extensions
Afbeelding 1 - Overzicht van te installeren extensions

De voorbeeld ADF-applicatie maakt gebruik van bounded task flows. Deze task flows kunnen eenvoudig worden getoond en getest via de extension ADF EMG Task Flow Tester.

Als je de applicatie in JDeveloper hebt geopend kan je deze starten via het menu Run | Choose Active Run Configuration | Task Flow Tester (kan ook via groene run icon en kies vervolgens Task Flow Tester).

Starten van een Task Flow Tester via JDeveloper Run Menu
Afbeelding 2 - Starten van Task Flow Tester via JDeveloper run menu

ADF EMG Task Flow Tester

De ADF EMG Task Flow Tester is een web-based testing tool voor ADF bounded task flows. Met deze tool kan je eenvoudig task flows als eenheid testen (unit test) met eventueel bijbehorende parameters. Je kunt ook task flow testcases direct vastleggen voor eenvoudig hergebruik van testen.

Vastleggen van testcases kan je doen in een XML-bestand met een vaste naam en locatie ViewController/src/adf-emg-task-flow-tester.xml.

Code snippet van ViewController/src/adf-emg-task-flow-tester.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TaskFlowTester xmlns="http://adf.emg.org/tftester">
    <TaskFlow displayName="showAllEmpsPerDeptTF"
              taskFlowId="/WEB-INF/taskflows/showAllEmpsPerDeptTF.xml#showAllEmpsPerDeptTF">
        <TestCase name="Department 30" runAsCall="false" runInRegion="true" stretchLayout="true">
            <ParamValueObject name="inputParameterDeptId" className="java.lang.String" valueAsString="#{30}"/>
        </TestCase>
    </TaskFlow>
</TaskFlowTester>

De Task Flow Tester wordt in de default browser getoond zodra de Integrated WebLogic Server is gestart. Dit is de link voor de Task Flow Tester http://127.0.0.1:7101/ViewController/faces/tftester

Overzicht van de Task Flow Tester in de browser
Afbeelding 3 - Overzicht van de Task Flow Tester in de browser

Debuggen van de ADF EMG XML Data Control

Tijdens het ontwikkelen van een applicatie is niet altijd duidelijk wat voor XML-data een SOAP Web Service retourneert. Zelf gebruik ik vaak de opensource tool SoapUI om vast te stellen welke operaties een Web Service bevat en hoe bijvoorbeeld het vraag- en antwoordbericht van een operatie eruitziet. Je maakt in deze tool eenvoudig een project aan op basis van een WSDL, de tool genereert van alle operaties de vraagberichten en je kunt direct aan de slag.

Om Web Service antwoordberichten voorspelbaar te maken is het ook mogelijk om in SoapUI een Mock Service van een Web Service te maken waarbij je zelf het response bericht kan manipuleren. Hoe dit precies in zijn werk gaat kan je verder lezen in het artikel Mock Services in SoapUI.

Een andere manier om te kunnen zien wat voor antwoord XML-bericht er bijvoorbeeld binnenkomt (tijdens het uitvoeren van je applicatie), is door gebruik te maken van de standaard logging van de Integrated WebLogic Server. Ga naar het tabblad Running: IntegratedWebLogicServer en klik rechtsboven in het Actions menu voor Configure Oracle Diagnostic Logging. Zoek in dat scherm vervolgens naar het package org.adfemg.datacontrol.xml.DataControl en verander het log Level naar Fine.

Overzicht van de Oracle Diagnostic Logging Configuration
Afbeelding 4 - Overzicht van de Oracle Diagnostic Logging Configuration

Om nu te zien welk antwoordbericht er wordt uitgevoerd na een aanroep van de task flow showAllDepartmentsTF moet deze eerste éénmaal via de Task Flow Tester worden uitgevoerd. Ga vervolgens naar de logging via het hoofdmenu Tools | Oracle Diagnostic Log Analyzer. Kies linksboven voor By Log Message, type vervolgens als zoekargument 'data-provider' en klik Search. In onderstaande afbeelding zie je linksonder een begin van het XML-antwoordbericht

Overzicht van de Oracle Diagnostic Log Analyzer met detail bericht
Afbeelding 5 - Overzicht van de Oracle Diagnostic Log Analyzer met detail bericht

Maatwerk aan de ADF EMG XML Data Control

Soms is het zo dat een XML-antwoordbericht nou net niet die elementen bevat die jij nodig denkt te hebben. Als je een DataControl in je ADF-applicatie hebt gemaakt kan je het antwoordbericht aanpassen, dit wordt ook wel Customization genoemd. Via een Customization-Provider definitie in de DataControls.dcx is het mogelijk om voor een DataControl Java Class(es) vast te leggen. In zo’n Java Class kan dan weer via een annotatie @ElementCustomization een node worden aangegeven waarvoor er maatwerk moet worden gemaakt.

Code snippet Customization-Provider configuratie uit DataControl.dcx

<customization-provider class="org.adfemg.datacontrol.xml.provider.customization.CustomizationProviderImpl">
  <parameters>
    <list-parameter name="classes">
      <value>nl.wh.generic.datacontrols.hrservice.customization.CustomEmployee</value>
    </list-parameter>
  </parameters>
</customization-provider>

Als voorbeeld van een maatwerkaanpassing kan je bijvoorbeeld denken aan een optelsom van het maandsalaris van alle medewerkers van een afdeling om zo het gemiddelde te kunnen berekenen.

Handige tips bij het opzetten van jouw ADF-applicatie

Tip 1

Het is het overwegen waard om iedere ADF Datacontrol voor een SOAP Web Service onder te brengen in een nieuw project. Je XML Data Control definitie wordt altijd vastgelegd in DataControls.dcx. De locatie van dit bestand ligt vast in Project/adfmsrc/META-INF/adfm.xml. Alle operaties voor de SOAP Web Service die je wilt gaan gebruiken leg je hierin vast met alle daarbij behorende maatwerk Java Classes.

Code snippet van Project/adfmsrc/META-INF/adfm.xml

<?xml version="1.0" encoding="UTF-8" ?>
<MetadataDirectory xmlns="http://xmlns.oracle.com/adfm/metainf" version="11.1.1.0.0">
  <DataControlRegistry path="nl/wh/generic/datacontrols/hrservice/DataControls.dcx"/>
</MetadataDirectory>

Als je vervolgens in je ViewController project properties aangeeft dat dit project een afhankelijkheid heeft met het SOAP Web Service project (Custom project) dan wordt de zojuist genoemde DataControlRegistry automatisch overgenomen in het ViewController project. Deze configuratie wordt vastgelegd in ViewController/WEB-INF/classes/META-INF/adfm.xml.

Code snippet van ViewController/WEB-INF/classes/META-INF/adfm.xml

<?xml version = '1.0' encoding = 'UTF-8'?>
<MetadataDirectory xmlns="http://xmlns.oracle.com/adfm/metainf" version="11.1.1.0.0">
  <DataBindingRegistry path="nl/wh/mydatacontrol/view/DataBindings.cpx"/>
  <DataControlRegistry path="nl/wh/generic/datacontrols/hrservice/DataControls.dcx"/>
</MetadataDirectory>

Vervolgens zal er steeds een nieuwe DataControlRegistry aan het adfm.xml bestand worden toegevoegd zodra je weer een nieuw project met een DataControl.dcx toevoegt aan je applicatie.

Tip 2

De laatste tip die ik je niet wil onthouden heeft betrekking op het formatteren van bedragen en percentages. In ADF kan je optionele localization properties opgeven die onder andere bepalen hoe een bedrag wordt getoond. Denk dan aan een duizendtal scheidingsteken en een decimaal scheidingsteken. Deze gegevens kunnen worden vastgelegd in ViewController\public_html\WEB-INF\trinidad-config.xml.

Code snippet van ViewController\public_html\WEB-INF\trinidad-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
  <debug-output>true</debug-output>
  <decimal-separator>,</decimal-separator>
  <number-grouping-separator>.</number-grouping-separator>
  <formatting-locale>nl_NL</formatting-locale>
</trinidad-config>

In de ADF-pagina kan je bijvoorbeeld een oracle.adf.view.faces.converter.NumberConverter gebruiken (af:convertNumber) die er voor zorgt dat jouw data op de juiste manier naar de gebruiker toe wordt gepresenteerd. De opmerking die ik hierbij wil maken is dat het binding attribuut dat getoond moet worden niet van het type java.lang.String moet zijn want dan werkt de NumberConverter niet correct.

Code snippet van fragment showAllEmpsPerDept.jsff

<af:column headerText="salary" id="c4" align="right">
	<af:outputText value="#{row.salary}" id="ot4">
		<af:convertNumber type="number" minFractionDigits="2" maxFractionDigits="2" minIntegerDigits="1"/>
	</af:outputText>
</af:column>
<af:column headerText="salaryAsString" id="c6" align="right">
	<af:outputText value="#{row.salaryAsString}" id="ot6">
		<af:convertNumber type="number" minFractionDigits="2" maxFractionDigits="2" minIntegerDigits="1"/>
	</af:outputText>
</af:column>
<af:column headerText="salaryAsDouble" id="c7" align="right">
	<af:outputText value="#{row.salaryAsDouble}" id="ot7">
		<af:convertNumber type="currency" minFractionDigits="2" maxFractionDigits="2" minIntegerDigits="1"/>
	</af:outputText>
</af:column>

Overzicht van het fragment showAllEmpsPerDept.jsff (Employees for department)
Afbeelding 6 - Overzicht van het fragment showAllEmpsPerDept.jsff (Employees for department)

Een oplossing hiervoor kan zijn om in de XML Data Control Customization Class een nieuw transient attribuut op te nemen en de java.lang.String waarde om te zetten naar een class die een subclass is van java.lang.Number. Dit kan dan onder andere een BigDecimal, BigInteger, Double, Float, Integer, Long, of Short zijn. Een transient attribuut is in het geval van de XML Data Control een attribuut dat vergankelijk is, dus niet standaard in het antwoordbericht is opgenomen.

Code snippet van Customization Class CustomEmployee.java

@ElementCustomization(target =
	"nl.wh.generic.datacontrols.hrservice.HRServiceDC.getDeptEmps.DepartmentEmployeesResponse.Employee")
public class CustomEmployee {
    private static final String AMOUNT = "12300.375";
    @TransientAttr
    public String initSalaryAsString(XMLDCElement element) {
        return AMOUNT;
    }        
    @TransientAttr
    public Double initSalaryAsDouble(XMLDCElement element) {
        return Double.valueOf(AMOUNT);
    }        
}

Conclusie

Als je als ontwikkelaar snel resultaat wilt om data op het ADF-scherm te tonen, zonder dat daarvoor allerlei extra code moet worden geschreven, dan is de XML Data Control echt een uitkomst. Uiteraard behoort het updaten van data ook tot de mogelijkheden, maar ik heb mij in dit artikel beperkt tot het ophalen van data. Als je meer wilt dan het standaard antwoordbericht dan is er via het gebruik van Customization Classes voldoende ruimte om het bericht naar eigen inzicht uit te breiden.

Om de werking van alle bovenstaande tips nog eens door te nemen adviseer ik om de Demo applicatie MyXmlDatacontrol te downloaden en in detail verder te bekijken en uit te proberen.

Links en referenties

Waardering:
 

Reacties

Nieuwe reactie inzenden

De inhoud van dit veld is privé en zal niet openbaar worden gemaakt.

Meer informatie over formaatmogelijkheden

CAPTCHA
Deze vraag is om te testen of u een persoon bent en om spam te voorkomen
Image CAPTCHA
Enter the characters shown in the image.