Web services in Java SE, Part 1

Learn all about Web services and how they work in Java SE

jw javaqa webservicesp1jpg
Soil Science

Java Standard Edition (SE) 6 included support for Web services. This post begins a four-part series on Web services in Java SE by explaining what Web services are and overviewing Java SE's support for them. Future posts will use this support to build SOAP-based and RESTful-based Web services, and will also cover advanced Web service topics.

What are web services?

Wikipedia defines Web service as "a software system designed to support interoperable machine-to-machine interaction over a network." A more detailed definition can be obtained by first defining this term's parts:

  • Web: An enormous interconnected network of resources, where a resource is a Uniform Resource Identifier (URI)-named data source such as a PDF-based document, a video stream, a Web page, or even an application. These resources can be accessed by using standard Internet protocols such as HyperText Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP).
  • Service: A server-based application or software component that exposes a resource to clients via an exchange of messages according to a message exchange pattern (MEP). The request-response MEP is typical.

Given these definitions, a Web service is a server-based application/software component that exposes a Web-based resource to clients via an exchange of messages. These messages may be formatted according to Extensible Markup Language (XML) or JavaScript Object Notation (JSON). Also, these messages can be thought of as invoking Web service functions and receiving invocation results. Figure 1 illustrates this message exchange.

Figure 1. A client accesses a resource by exchanging messages with a Web service

A client accesses a resource by exchanging messages with a Web service

Web services can be classified as simple or complex. Simple Web services don't interact with other Web services (e.g., a standalone server-based application with a single function that returns the current time for a specified time zone). In contrast, complex Web services often interact with other Web services. For example, a generalized social network Web service might interact with Twitter and Facebook Web services to obtain and return to its client all Twitter and all Facebook information for a specific individual. Complex Web services are also known as mashups because they mash (combine) data from multiple Web services.

SOAP-based web services

A SOAP-based Web service is a widely used Web service category that's based on SOAP, an XML language for defining messages (abstract function invocations or their responses) that can be understood by both ends of a network connection. An exchange of SOAP messages is called an operation, which corresponds to a function call and its response, and which is depicted in Figure 2.

Figure 2. A Web service operation involves input and output messages

A Web service operation involves input and output messages

Related operations are often grouped into an interface, which is conceptually similar to a Java interface. A binding provides concrete details on how an interface is bound to a messaging protocol (particularly SOAP) to communicate commands, error codes, and other items over the wire. The binding and a network address (an IP address and a port) URI is known as an endpoint, and a collection of endpoints is a Web service. Figure 3 presents this architecture.

Figure 3. Interfaces of operations are accessible via their endpoints

Interfaces of operations are accessible via their endpoints

SOAP is often used with Web Services Description Language (WSDL, pronounced whiz-dull), an XML language for defining a Web service's operations. A WSDL document is a formal contract between a SOAP-based Web service and its clients, providing all details for interacting with the Web service. This document lets you group messages into operations and operations into interfaces. It also lets you define a binding for each interface as well as the endpoint address.

As well as supporting WSDL documents, SOAP-based Web services have the following properties:

  • The ability to address complex nonfunctional requirements such as security and transactions: These requirements are made available via various specifications. To promote interoperability among these specifications, the Web Services Interoperability Organization (WS-I) (an industry consortium) was formed. WS-I has established a set of profiles, where a profile is a set of named Web service specifications at specific revision levels, along with a set of implementation and interoperability guidelines recommending how the specifications may be used to develop interoperable Web services. For example, the very first profile, WS-I Basic Profile 1.0, consists of the following set of nonproprietary Web service specifications:
  • SOAP 1.1
  • WSDL 1.1
  • Universal Description Discovery and Integration (UDDI) 2.0
  • XML 1.0 (Second Edition)
  • XML Schema Part 1: Structures
  • XML Schema Part 2: Datatypes
  • RFC2246: The Transport Layer Security Protocol Version 1.0
  • RFC2459: Internet X.509 Public Key Infrastructure Certificate and CRL Profile
  • RFC2616: HyperText Transfer Protocol 1.1
  • RFC2818: HTTP over TLS
  • RFC2965: HTTP State Management Mechanism
  • The Secure Sockets Layer Protocol Version 3.0

Additional profile examples include WS-I Basic Security Profile and Simple SOAP Binding Profile. For more information on these and other profiles, visit the WS-I website. Java SE supports the WS-I Basic Profile.

  • The ability to interact with a Web service asynchronously: Web service clients should be able to interact with a Web service in a nonblocking, asynchronous manner. Client-side asynchronous invocation support of Web service operations is provided in Java SE.

SOAP-based Web services execute in an environment that includes a service requester (the client), a service provider, and a service broker. This environment is shown in Figure 4.

Figure 4. A SOAP-based Web service involves a service requester, a service provider, and a service broker (e.g., UDDI)

A SOAP-based Web service involves a service requester, a service provider, and a service broker (e.g., UDDI)

The service requester, typically a client application (e.g., a Web browser), or perhaps another Web service, first locates the service provider in some manner. For example, the service requester might send a WSDL document to a service broker, which responds with another WSDL document identifying the service provider's location. The service requester then communicates with the service provider via SOAP messages.

Service providers need to be published so that others can locate and use them. In August 2000, an open industry initiative known as Universal Description, Discovery, and Integration (UDDI) was launched to let businesses publish service listings, discover each other, and define how the services or software applications interact over the Internet. However, this platform-independent, XML-based registry wasn't widely adopted and currently isn't used. Many developers found UDDI to be overly complicated and lacking in functionality, and opted for alternatives such as publishing the information on a website. For example, Google once made its public Web services (e.g., Google Maps) available at http://code.google.com/more/.

The SOAP messages that flow between service requesters and service providers are often unseen, being passed as requests and responses between the SOAP libraries of their Web service protocol stacks. However, it's possible to access these messages directly, as you will discover later in this series.

RESTful web services

SOAP-based Web services can be delivered over protocols such as HTTP, SMTP, FTP, and Blocks Extensible Exchange Protocol (BEEP). Delivering SOAP messages over HTTP can be viewed as a special kind of RESTful Web service.

A RESTful Web Service is a widely used Web service category that's based on Representational State Transfer (REST), a software architecture style for distributed hypermedia systems (systems in which images, text, and other resources are located around networks and are accessible via hyperlinks). The hypermedia system of interest in a Web services context is the World Wide Web.

The central part of REST is the URI-identifiable resource. REST identifies resources by their Multipurpose Internet Mail Extensions (MIME) types (such as text/xml). Also, resources have states that are captured by their representations. When a client requests a resource from a RESTful Web service, the service sends a MIME-typed representation of the resource to the client.

Clients use HTTP's POST, GET, PUT, and DELETE verbs to retrieve resource representations and to manipulate resources. REST maps these verbs onto the database Create, Read, Update, and Delete (CRUD) operations, as follows:

  • POST: Create new resource based on request data.
  • GET: Read existing resource without producing side effects (don't modify the resource).
  • PUT: Update existing resource with request data.
  • DELETE: Delete existing resource.

Each verb is followed by a URI that identifies the resource. (This immensely simple approach is fundamentally incompatible with SOAP's approach of sending encoded messages to a single resource.) The URI might refer to a collection, such as http://javajeff.ca/library, or to an element of the collection, such as http://javajeff.ca/library/9781484219157 -- these URIs are only illustrations.

For POST and PUT requests, XML-based resource data is passed as the body of the request. For example, you could interpret POST http://javajeff.ca/library HTTP/ 1.1 (where HTTP/ 1.1 describes the requester's HTTP version) as a request to insert POST's XML data into the http://javajeff.ca/library collection resource.

For GET and DELETE requests, the data is typically passed as query strings, where a query string is that portion of a URI beginning with a ? character. For example, where GET http://javajeff.ca/library might return a list of identifiers for all books in a library resource, GET http://javajeff.ca/library?isbn=9781484219157 would probably return a representation of the book resource whose query string identifies International Standard Book Number (ISBN) 9781484219157.

REST also relies on HTTP's standard response codes, such as 404 (requested resource not found) and 200 (resource operation successful), along with MIME types (when resource representations are being retrieved).

Web service support in Java SE

Before Java SE 6, Java-based Web services were developed exclusively with the Java Enterprise Edition (EE) SDK. Although Java EE is preferred for developing Web services from a production perspective, because Java EE-based servers provide a very high degree of scalability, a security infrastructure, monitoring facilities, and so on, the repeated deployment of a Web service to a Java EE container has often been time consuming, slowing down development. Java SE 6 simplified and accelerated Web services development by adding APIs, annotations, tools, and a lightweight HTTP server (for deploying Web services to a simple Web server and testing them in this environment) into its core.


Java SE provides several APIs that support Web services. Along with various JAXP APIs (SAX, DOM, StAX, and so on) that I discuss in Java XML and JSON, Java SE provides the JAX-WS, JAXB, and SAAJ APIs:

1 2 Page 1