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

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.

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

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

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.

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.

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.

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).

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.

Press Next.

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

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

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

Press Next.

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

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.

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

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.

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.

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:

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

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:

Click on the OK button.

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

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.

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.

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

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.

Press the OK button.

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.

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:

The Deployment Wizard appears.

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

Press Next.

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

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.

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

Press Next.

The Summary appears.

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:

Invoke the operation getEmployeeByKey for employeeId 102, results in:

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

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.

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:

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:

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”