April 2015 - Collaborate/IOUG

1. COLLABORATE 15 – IOUG Forum
Development
1 | P a g e “Understanding and Developing Web Services – For DBAs and Developers”
White Paper
Understanding and Developing Web Services – For DBAs and
Developers
Ahmed Aboulnaga, Raastech
Harold Dost III, Raastech
ABSTRACT
WSDL. XSD. SOAP. Namespaces. Port types. If these terms make little sense, this presentation is for you. By the end of this
presentation, you will completely understand how to dissect and decipher a web service interface, understand key design
patterns, and learn how to develop top-down and bottom-up web services in technologies such as Java and Oracle SOA Suite.
TARGET AUDIENCE
This white paper is intended for DBAs and developers who have never developed a SOAP web service before and are looking
to understand what it takes. A basic background in programming is required.
EXECUTIVE SUMMARY
Learner will be able to:
 Obtain a thorough and deep understanding of all pieces of the web service interface.
 Learn how to develop web services in Java, SOA, and OSB.
 Understand the difference between top-down and bottom-up web service development.
BACKGROUND
In the past, when you wanted to make an application call from one application to another, you would have to familiarize
yourself with the implementation language of the called application. If you are a Java application looking to make a call to a
PL/SQL procedure, then you must import all the necessary Oracle Database libraries into your Java application to successfully
invoke the stored procedure. As more and more applications entered the enterprise, this became development nightmare.
This is where web services gained popularity. In its ability to offer a standardized approach to call in and out of web services, it
no longer mattered if you were a C#, .NET, Java, or PL/SQL application. Your call to the external application is done over a
common standard supported by all, SOAP over HTTP. By standardizing on web services, and in specific, SOAP over HTTP,
there is no need to worry about the implementation technology of the target application.
TECHNICAL DISCUSSIONS AND EXAMPLES

2. COLLABORATE 15 – IOUG Forum
Development
2 | P a g e “Understanding and Developing Web Services – For DBAs and Developers”
White Paper
Dissecting a WSDL
PL/SQL is a programming language no different than other programming languages. In the first snippet, this is a simple
procedure that accepts a zipcode as the input and returns the temperature as the output. This is a simple procedure that has real
world value. In the world of web services, this is referred to as a request-response type of call, or synchronous call. The second
snippet demonstrates a 1-way or asynchronous invocation where in no response is returned to the caller.
Each PL/SQL procedure has a name, input, and optional output parameters. And most PL/SQL packages have a header that
defines the interface to the package. The package header merely provides the developer with the information necessary to call
the package. This is similar to a web service WSDL.
WSDL stands for “Web Services Description Language”. It is an XML document that describes a web service (i.e., it is the
interface specification for the web service). It specifies the location of the web service, the operations it supports, and the
message types.
Web services are typically accessed via an HTTP URL similar to the following:
 http://sandbox.raastech.com/jws/weather?WSDL
Opening up the WSDL in a web browser reveals the interface to the web service, which is simply the definition of this web
service, giving the developer enough information to make the call. This interface is identical to a package header.
In the web service below, there are color coded highlighted sections that we would like to focus on.
 GREEN: Here, it describes the operation of the web service; getWeather. This is no different than the PL/SQL
procedure name shown in the previous figure. In it, we can see that this operation has an input parameter and an
output parameter.
 RED: This section merely states that the input parameter zipRequest is definition of of zipcode as shown in the gray
section.
 GRAY: The elements here have the specifics of the message. For example, zipcode is of type integer.
 BLUE: Lastly, this WSDL has another URL inside of it! This is referred to as the endpoint. It merely describes the
location of where the actual binary code resides. In the majority of cases, this is on the same server as the WSDL, but
not necessary.

3. COLLABORATE 15 – IOUG Forum
Development
3 | P a g e “Understanding and Developing Web Services – For DBAs and Developers”
White Paper
Web Service Concepts
In the References section at the end of this white paper are a series of links to w3schools, and excellent beginner resource for
those wanting to embark on web service development. Most of us are already familiar with XML, but it’s the details, specifics,
and terminology that is lost to the majority of developers.
Introduction to: XML Structure
This white paper is not intended to duplicate what is already on the w3schools.com website, so we will merely list a few points
worth considering here:
 XML documents follow a tree structure.
 Every XML document must have 1 root element.
 The root element is the parent of all other elements.
 Comments take the form <!-- a comment -->.
 Unlike HTML, XML documents must have open and close tags, and the open and close tags are case sensitive.
 XML elements must be properly nested. For example, this is improper XML: <b><u>Hello</b></u>
 Entity reference, for example, is using &lt; to represent the < sign.
 Unlike HTML, white space is preserved in XML <Name>John Doe is 23 years old.</Name>.
Introduction to: XML Schema
<definitions name="Weather">
<types>
<schema>
<element name="zipcode" type="integer"/>
<element name="temperature" type="string"/>
</schema>
</types>
<message name="zipRequest"><part name="parameters" element="zipcode"/></message>
<message name="tempResponse"><part name="parameters" element="temperature"/></message>
<portType name="WeatherPort">
<operation name="getWeather">
<input message="zipRequest"/>
<output message="tempResponse"/>
</operation>
</portType>
<binding name="WeatherBinding" type="WeatherPort">
<operation name="getWeather">
<input name="zipRequest"/>
<output name="tempResponse"/>
</operation>
</binding>
<service name="WeatherService">
<port name="WeatherPort" binding="WeatherBinding">
<soap:address location="http://localhost/wc/weather"/>
</port>
</service>
</definitions>

4. COLLABORATE 15 – IOUG Forum
Development
4 | P a g e “Understanding and Developing Web Services – For DBAs and Developers”
White Paper
An XML schema defines the elements in an XML document. In the WSDL shown above, the XML Schema is within the
<schema> tags. The name, type, and constraints of each element (i.e., variable) is defined here.
 XML Schema defines elements in an XML document.
 XML Schema defines attributes in an XML document.
 XML Schema defines child elements, and optionally their number and order.
 XML Schema defines data types for both elements and attributes.
 XML Schema defines default and fixed values for elements and attributes.
 XML Schemas are well-formed XML documents and are extensible.
 They are typically saved as .xsd files and imported into a WSDL.
 The root element of every XML Schema is the <schema> element.
 The <schema> element may include attributes such as the XML namespace.
An XML schema is comprised of either one or more simple elements or complex elements.
 A simple element contains only plain text that can be defined in one of several predefined data types (or custom
types).
 The predefined data types in XML Schema include: string, decimal, integer, boolean, date, time
 Complex elements are XML elements that contains other elements or attributes.
Introduction to: SOAP
SOAP is a communication protocol and allows XML documents to be exchange over HTTP.
 SOAP stands for “Simple Object Access Protocol”.
 As a result, it is platform and technology independent, and ideal for Internet-based communication.
 A SOAP message is an XML document that contains the following: envelope, header (optional), body, fault (optional)
Below is an example of a SOAP message. This constitutes the entire message that is sent to the web service.
An envelope is the root element of a SOAP message. A header is optional and, for example, may contain information such as
authentication specifics. The header is the first child element of the envelope element. The body is always required and contains
the content of the SOAP message (i.e., the payload).
Java Web Service Development
In the References section, there are two links that walk through the development of a top-down and a bottom-up Java web
service. In face, you do not have to be a seasoned Java developer to implement a fully functioning production quality web
service in Java.
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope">
<soap:Body>
<m:Customer xmlns:m="http://raastech.com/Customer">
<m:Name>John Doe</m:Name>
</m:Customer>
</soap:Body>

5. COLLABORATE 15 – IOUG Forum
Development
5 | P a g e “Understanding and Developing Web Services – For DBAs and Developers”
White Paper
A top-down web service basically begins with a WSDL. You must have a WSDL that defines the operations, messages, and
schema. Once imported into Oracle JDeveloper 11g or 12c, through a series of navigation and clicks, stubs for the underlying
Java classes are created. Simply stick in your logic there! Walkthrough instructions provided here:
 http://blog.raastech.com/2009/01/creating-top-down-java-web-service-for.html
A bottom-up web service is the reverse. In this scenario, you begin with an already pre-existing Java class. Through a series of
right-clicks and wizards, you can easily expose the Java class and methods as a web service interface with little to no
programming involved! Walkthrough instructions provided here:
 http://blog.raastech.com/2009/03/creating-bottom-up-java-web-service-for.html
SOAP vs. REST
This white paper focused on SOAP-based web services. Emerging as the new challenger is REST-JSON. SOAP has strong
message type validation and based on the XML standard. Unfortunately, message payloads are typically heavy and not as
lightweight as REST. Compare the two messages below; SOAP and REST-JSON.
The Oracle A-Team released a performance study comparing SOAP versus REST for mobile applications and the results are
heavily tilted towards REST-JSON. The study can be found here: http://www.ateam-oracle.com/performance-study-rest-vs-
soap-for-mobile-applications/
REFERENCES
Web service concepts:
 http://www.w3schools.com/xml/default.asp
 http://www.w3schools.com/schema/default.asp

6. COLLABORATE 15 – IOUG Forum
Development
6 | P a g e “Understanding and Developing Web Services – For DBAs and Developers”
White Paper
 http://www.w3schools.com/xpath/default.asp
 http://www.w3schools.com/xsl/default.asp
 http://www.w3schools.com/xquery/default.asp
 http://www.w3schools.com/webservices/default.asp
 http://www.w3schools.com/webservices/ws_wsdl_intro.asp
 http://www.w3schools.com/webservices/ws_soap_intro.asp
Java web service development walkthrough:
 http://blog.raastech.com/2009/01/creating-top-down-java-web-service-for.html
 http://blog.raastech.com/2009/03/creating-bottom-up-java-web-service-for.html
Performance Study – REST vs SOAP for Mobile Applications
 http://www.ateam-oracle.com/performance-study-rest-vs-soap-for-mobile-applications/