As explained in the introduction of this chapter, SOAP stands for Simple Object Access Protocol. It is a standard that defines how the message that calls the webservice should be defined and how the answer is returned. Both messages are in XML.
SOAP webservices can be defined in so-called Web Service Description Language (WSDL for short) documents. By reading a WSDL, an application knows what webservices are available, how to call them, and what response it can expect back. APEX uses the information in a WSDL document to generate the SOAP messages, without the developer having to do any programming.
In this recipe, we are going to show how we can call a SOAP webservice, using built-in functionality of Application Express.
Have an application ready. It doesn't have to be empty, as long as we can add new pages.
Also make sure that if you are working on an Oracle 11g database, that the host of each webservice that we are going to use is entered into the Access Control List (ACL) for the APEX user.
The ACL is a structure to allow access to network services. In earlier versions of the database, access was essentially granted to all services or none. In 11g this has been changed, so it is now possible to allow fine grained access to selected network services.
To allow the APEX_040000 user access to a network service like a webservice, we can use the following script:
begin dbms_network_acl_admin.create_acl (acl => 'acl_user.xml' ,description => 'Description' ,principal => 'APEX_040000' ,is_grant => true ,privilege => 'connect' ,start_date => null ,end_date => null); -- dbms_network_acl_admin.add_privilege (acl => 'acl_user.xml' ,principal => 'APEX_040000' ,is_grant => true ,privilege => 'resolve'), -- dbms_network_acl_admin.assign_acl (acl => 'acl_user.xml' ,host => 'name of website or host, i.e. soap.amazon.com'), -- commit; end;
[1346_08_01.txt]
This piece of code will do three things.
- It will create a new entry in the ACL for the APEX_040000 user, to allow this user to connect to network and/or internet resources.
- It will add a privilege for the same user to resolve addresses.
- It will assign a certain hostname to the ACL entry.
So these three together will allow the APEX_040000 user to resolve a network address and connect to it.
The ACL entries can be inspected by querying the database using the following query as a DBA user:
select * from dba_network_acls;
Their associated privileges can be found by using the following query, again as a DBA user:
select * from dba_network_acl_privileges;
Instead of a single URL for the host, a wildcard ('*') can be entered. But be careful when doing this, because this will allow any APEX user to connect to any network and internet address from any APEX application or PL/SQL code.
In this recipe, we are going to create a page and a report based on a webservice using the information from a WSDL document.
- Navigate to the Web Service Reference overview by going to Shared Components and Web Service References.
- Click the Create button.
We are now in the wizard that will guide us through the creation process. On the first screen choose Based on WSDL and click Next.
- Select No when asked if we want to search a UDDI registry and click Next.
- For the WSDL location, enter http://ws.cdyne.com/WeatherWS/Weather.asmx?wsdl.
- Click Next.
- In the following screen, change the name to CDYNE Weather. Leave everything else on its default value and click Create Reference.
We can see that APEX has gathered some information about the webservice by calling the WSDL document. It has found the name of the webservice, its endpoint and more importantly, the available operations to use. Later in the recipe, we will use the GetCityWeatherByZIP operation.
After creating the webservice reference, APEX gives us the option to inspect it or continue directly to build a page using the reference.
- Click Create Form on Web Service to continue.
- From the available references in the pulldown on the next page, select CDYNE Weather.
- A new select list appears with the available operations. Select GetCityWeatherByZIP and click Next.
- Application Express will now show a list of default properties. When necessary change the page number, else leave the values on their default and click Next.
The next screen will allow us to create items that can be used in the webservice call. These have been generated based on the information from the WSDL. If the page number has changed, then rename the items accordingly. In this case, there is only one parameter, the input parameter to hold the zipcode for our webservice request.
- Change the Item Label to Zipcode and click Next.
- The next screen is the same principle, but for output parameters. APEX has generated 15 items—one for each possible item in the response. This screen might look a little strange, but that should be fixed in a later version of Application Express. Click Next.
- Select the tab that you want to use or create a new tab and click Next.
- Click Create Form and run the Page.
You will see that APEX has created a straightforward page for us that will allow us to enter the required input parameter for the webservice. It has also created text fields for all the output parameters.
Try the webservice by entering an American zip code into the appropriate field (for the non-Americans; everybody remembers 90210 don't we?) and pressing Submit. This will result in the webservice returning an XML file with weather information for the chosen city. APEX automatically translates this data and enters it into the right fields on the screen.
