Quickly creating, deploying and testing a WebService interface for ADF Business Components

5

As you probably already know, ADF Business Components can very easily be exposed through a WebService interface. An Application Module can be configured with a Service Interface, ordinary ViewObjects and custom methods can be exposed in that interface and deployment is relatively straightforward. In minutes, a WebService can be published that exposes operations based on regular ADF BC functionality. This may well give us the fastest way to provide data services on top of a relational database. Several excellent articles have been published on the ADF BC service interface, for example by Steve Muench and Andrejus Baranovskis.

The blog-article you are reading is created as the result of my research and investigations around an article I hope to publish in Oracle Magazine later in 2011. It is adamant for this article that readers can get the example to work with the smallest number of instructions possible – both to make their life easy and to save on words. The article describes a BPM process that interacts with the HR schema of an Oracle RDBMS as one of its activities. The focus in the article will be on BPM, not on exposing data services for the HR schema. The WebService should therefore be available in a starter application, and be deployable without any fuzz or configuration overhead.

This blog-article demonstrates how to rapidly create the HRService – an ADF BC driven WebService on top of the EmployeesView ViewObject that exposes the EMPLOYEES table in the HR schema through the Employee EntityObject. However, its true purpose is to show how to create the deployment profile and deploy and test this service, either on the integrated WLS or on a standalone WebLogic Server, in the easiest way possible. Note that this easiest way is not the suggested way of working for real production environments.

This article assumes – in case you want to follow along for yourself – that you have JDeveloper 11g PS2, Oracle RDBMS 10gR2 or later with the HR sample schema and the SOA Suite 11g Run Time environment.

Create the ADF BC Project

First create a new JDeveloper application, either a Generic Application or one based on a specific Application Template, such as SOA or BPM application. Then create the ADF Model project that will contain the ADF Business Components that are to be exposed as Web Service.

001 createModelPrj

Specify the name of project, for example Model. Press Next.

002 projNameAndLibs

Specify the name of the default package, in this case org.hrm and press Finish.

003 prjPackages

The Project is created and added to the Application. Click on the New icon or the File | New menu option to start creating the Business Component definitions. Select the option Business Components from Tables under Business Tier | ADF Business Components.

004 bcfromtable

Click OK.

Our business components are defined on top of database objects. Those can only be accessed through a database connection. We first need to create and configure that database connection before moving on with the definition of the business objects. Click on the green plus icon to create a new connection.

005 initializeConnection

The Create Database Connection editor is presented. Specify the connection details for connecting to the HR schema in the database instance you want to work against.

006 configureConnection

Test the connection by pressing the Test Connection button and wait for the Success! message to appear. When it does, press OK. (when it does not, fiddle with your configuration details until it does).

007 connectionEstablished

Press OK to confirm the use of this HR database connection.

In the Entity Objects page that appears next, query the database objects, select the EMPLOYEES table, move it to the selection on the right side and specify the Entity Name as Employee.

008 selectEmployeesTable

Press Next.

Select the EmployeeView ViewObject as Updateable View Object and change its name to EmployeesView.

009 defineEmployeesView

Press Next. Do not select any Read Only View Objects. Press Next.

Specify the Name of the Application Module to create as HRService.

010 configureAppMod

Press Next.

The summary of all we have configured in the wizard is presented.

011 summaryADFBC

Press Finish to complete the wizard and confirm all the objects for creation.

Configure the Service Interface

Adding a Service Interface to the Application Module is a simple, declarative task. We indicate that the AM should have a Service Interface, what its name should be and then we specify which custom methods (none in our case) and which ViewObjects (one in our case) are to be included in the interface. For each ViewObject we can also specify which of the basic CRUD operations should be supported.

Double click the HRService in the Application Navigator. In the editor, select the tab Service Interface.

012 configureServiceInterface

Click on the green plus icon to add a new Service Interface to the definition of the Application Module.

013 WebServiceNameAndNS

Specify the name as HRService (that name will eventually make it into the Endpoint URL for the WebService) and the target namespace as (the default) /org/hrm/common/.

Press Next.

Do not select any custom methods in the second step (we do not have any) and move on to step 3.

014 selectVOandCRUDMethods

Select the EmployeesView1 ViewObject. Check the boxes for the Update and GetByKey operation – as these are the only two required for the business case discussed in the BPM article that this service is created for – and change the names of the methods to something readable. Note: these method names will become the operation names in the WSDL for the Web Service.

Press Next. The Summary appears.

015 completeServiceInterface

Press Finish to create the Service Interface with the single Service View Instance.

We will now do two things to make it easier later on to deploy the ADF BC application with minimal configuration overhead. First, open the Configurations tab in the HRService Application Module editor. Select the configuration HRService as the Default Configuration for this application module:

025 setADFBCDefaultConfig

Then press select the HRService Configuration and press the pencil icon to edit the details for this configuration.

026 selectJDBCURLforAppModConfig

Change the Connection Type for this Configuration from JDBC DataSource to JDBC URL. This will allow deployment that includes the database connection details without us having to configure a JDBC Data Source on the target Application Server. Note: this is NOT a good practice for production environments – we do this only to achieve effortless deployment for test purposes.

Preparing for Deployment on a stand alone Application Server

The ADF BC Service Interface is deployed using a special Deployment Profile, of type Business Components Service Interface. We will create that deployment profile next.

Click on the New icon – of the File | New menu option – to bring up the New Gallery. Select General | Deployment Profiles and select Business Components Service Interface:

016 createBCSIDeploymentProfile

Click on the OK button.

017 ADFBCSIDeploymentProfile

Specify HRServices as the name for the Deployment Profile. Press OK.

018 afterCreatingDeploymentProfile

The Project Properties editor is brought up. The new deployment profile is presented, with its two constituents: Common and Middle Tier.

Press OK to close the editor.

Next, a special Application level Deployment Profile is created. Open the Application dropdown menu from the little icon shown in the upper right hand corner of the application navigator, behind the name of the application.

019 openApplicationProperties

Select the option Application Properties.

Select the Deployment node in the navigator and click on the New button to create a new Deployment Profile for the application.

020 createNewAppDeploymentProfile

Select EAR File (default) as Archive Type. Type HRServices as the name of the deployment profile.

021 newEARtypeAppDeplProfile

Press the OK button.

In the EAR Deployment Profile editor, select the node Application Assembly. Check the checkbox for Middle Tier in the HRServices deployment profile (of type Business Components Service Interface) that we have previously created.

022 defineApplicationAssembly

Press the OK button.

023 completeApplDeploymentProfileUncheckAutogenerate

Back in the Deployment page for the Application Properties, make sure that the checkbox Auto Generate and Synchronize weblogic-jdbc.xml Descriptors During Deployment is unchecked.

Press OK.

In order to have a nicer looking URL for the WebService endpoint as well as a better looking name for the application itself, we will open the Project Properties editor for the Model project, and open the Java EE Application node.

024 setProjectPropsJEEWebAppNameAndRoot

Set the Java EE Web Application Name and the Java EE Web Context Root (that will be part of the URL) to HRDataServices. Press OK to save these changes.

Prepare the stand alone application server

There is one important setting that you need to apply to the WLS domain that you will be deploying the ADF BC Web Service to (see also http://radalcove.com/blog/?p=16). This setting is is required to prevent the “Null Password given” error message that otherwise results when we access the Web Service. Simply put this setting instructs the WLS domain to accept passwords in deployed application.

Open the setDomainEnv.cmd or setDomainEnv.sh file – depending on your operating system – in the directory [WLS_HOME]\user_projects\domains\[your target domain]\bin and add the following line after the first occurrence of set JAVA_PROPERTIES.

set JAVA_PROPERTIES=%JAVA_PROPERTIES% -Djps.app.credential.overwrite.allowed=true

Deploying to a stand alone application server

We are now ready to deploy the application to a stand alone WebLogic Server domain. Note that I am assuming that you already have configured a connection to the target WLS domain. We will use that connection for the upcoming deployment.

Open the context menu for the Application – the same dropdown we used for creating the deployment profile for the application. Open the submenu Deploy and Select the HRServices deployment profile:

028 deployJEEApplicationRemote

The Deployment Wizard appears.

In the first step, elect to deploy to Application Server:

029 deployWizardStep1

Press Next.

In the second step, select the connection to the target Application Server, in my case the SOA_Suite11g_Local application server connection.

030 deployWizardStep2 pickAConn

Press Next.

Select the radio button Deploy to selected instances in the domain and select the target server(s) to which you want to deploy the ADF BC Service application.

031 deployWizardStep3TargetServers

Make sure that the radio button Deploy as standalone Application is selected.

Press Next.

The Summary appears.

032 deployWizardSummary

After a final review, press Finish to start the real deployment.

Testing the deployed Web Service application

After the deployment is complete, we can access the Web Service in its ‘runtime environment’. WebLogic Server provides easy support for testing webservices, available at the endpoint url for the WebServices, constructed from: http://servername:port_of_WLS_server/JEEapplication_contextroot/name_of_ADFBC_ServiceInterface which in our case resolves to http://localhost:8001/HRDataServices/HRService . Open that URL in your browser, and the following test interface is presented:

033 testWebServiceInBrowser

Invoke the operation getEmployeeByKey for employeeId 102, results in:

034 responseFromWebServiceTest

When you open the FMW Enterprise Manager console and inspect the HRServices application deployment, you will find something akin to the next screenshot:

035 HRServicesInFMWEM

Run ADF BC WebService locally in the integrated WebLogic Server

Even easier than deploying on a stand alone application server instance is the use of the Integrated WebLogic Server in JDeveloper. If you just want to test the functionality of the ADF BC Service Interface, you can run – which auto deploys on the integrated WLS instance – the HRServiceImpl.java class. This class was generated when we configured the Service Interface for the Application Module.

027 runHRServiceImplInIntegratedWLS

The Integrated WLS server is started – when not already running – and the ADF BC application is deployed on it. The Application’s Context Root and the Name of the Service Interface, together with localhost:7101, make up the endpoint url for the Web Service:

036 runLocallyInIntegratedWLS

You can open that URL in your browser, which will result in the same Test WebService UI as the stand alone WLS gave us previously:

037 TestInBrowserRunFromJDevInIntegratedWLS

Resources

Download the JDeveloper 11gPS2 application with the HRService Application Module described in this article: SalaryRaiseBPM.zip .

Andrejus Baranovskis: http://andrejusb.blogspot.com/2009/08/web-service-interface-for-adf-bc.html

ADF Developer’s Guide documentation: http://download.oracle.com/docs/cd/E12839_01/web.1111/b31974/bcextservices.htm#CJAJGIEB

Lynn Munsinger http://radalcove.com/blog/?p=16 for the gem on “-Djps.app.credential.overwrite.allowed”

Share.

About Author

Lucas Jellema, active in IT (and with Oracle) since 1994. Oracle ACE Director for Fusion Middleware. Consultant, trainer and instructor on diverse areas including Oracle Database (SQL & PLSQL), Service Oriented Architecture, BPM, ADF, Java in various shapes and forms and many other things. Author of the Oracle Press book: Oracle SOA Suite 11g Handbook. Frequent presenter on conferences such as JavaOne, Oracle OpenWorld, ODTUG Kaleidoscope, Devoxx and OBUG. Presenter for Oracle University Celebrity specials.

5 Comments

  1. Great post. One question: can you create ADF BC web service for a complex data types (i.e. master – detail VO/EO relationships)?

  2. Pingback: Android puts Oracle on the (Google) map. « AMIS Technology blog

  3. good post, but you didn’t explan how can I call this webservice from another ADF Application?

    Thanks

  4. Pingback: Quickly creating, deploying and testing a WebService interface for ADF Business Components