Nowadays, the World Wide Web is being used more and more for making applications that communicate with each other, in addition to the kind of human-computer interaction that was prevalent in the early days.
Whenever an application provides some kind of interface that can be programmatically invoked by another application by sending some command using the HTTP protocol, we say that this is an example of a Web Service.
The Alfresco repository is a set of Java classes that provide services to client applications for creating, manipulating, searching, and transforming content and for performing a host of additional operations such as checking and managing permissions, executing content-centric business processes, classifying content, and so on.
The publicly accessible entry points that clients can access to perform such operations make up the so-called Alfresco Foundation APIs. This is the lowest layer of APIs that can be used by client code, and all the other APIs, such as JCR and the JavaScript ones, all of the network protocols supported by Alfresco (CIFS, FTP, NFS, WebDAV, IMAP), and the Alfresco Explorer web-based frontend, call this layer in the end. There isn't any feature provided by the Alfresco repository that cannot be exploited using the Foundation APIs. However, the Foundation APIs have two main constraints:
1. The first constraint is that they are implemented as Java libraries. As long as you are developing your client applications using Java, this is not going to be too much of a limiting factor. But calling Java libraries from other languages, though possible in some circumstances, can be cumbersome and difficult.
2. The second constraint is that by using the Foundation APIs, you effectively end up embedding the Alfresco repository in your application. This is what the
alfresco.warpackage does—it contains the Alfresco Explorer (Web Client) application and that embeds the Alfresco Repository, via the Foundation APIs in turn.
The problem here is that only one application at a time can embed the Alfresco repository. If you try to have two distinct applications embed a copy of Alfresco, both configured to act on the same storage (database, content store, and indexes), and try to run them at the same time, you will end up corrupting the contents of the repository.
If you intend to run the Alfresco Explorer, this will be one application embedding the repository, and you will not be able to have another custom application do the same. Therefore, if you want to develop your own custom application on top of Alfresco, using the Foundation APIs, you have no choice but to develop and deploy it as an extension of the explorer or to embed Alfresco inside your application exclusively and give up the explorer.
Web Services provide a way out of this conundrum by exposing the features of the Alfresco Repository through a layer of services that can be invoked remotely over the network by exchanging messages over HTTP. This frees client applications from having to embed Alfresco—there will be only one repository, usually embedded in the Explorer, that also provides network-accessible services for remote clients to call.
These kind of Web Services are also language-agnostic, which means that you are not limited to using Java for implementing your client application, but you are also free to use any language, as long as it provides a way to send and receive messages using the HTTP protocol and is able to parse and generate messages using some well-known format such as XML.
You are also not forced to develop your application as a Web application. Creating a native GUI client, a Flash, or an iPhone application can be a perfectly reasonable choice.
The organizations that oversee the creation of new standards for the Web most notably the World Wide Web Consortium (W3C) have, since a long time, acknowledged the necessity of defining a set of technologies. This set would favor the interoperability of applications running on different hardware and software architectures and is developed using the most disparate programming languages and platforms.
These technologies are mostly based upon the XML language, which include a protocol called Simple Object Access Protocol (SOAP). This protocol has been defined with the purpose of letting heterogeneous applications, running in a distributed, decentralized environment, exchange structured messages. Providing an extended description of SOAP is beyond the scope of this book, as there are many other printed and online resources covering it in minute detail. A few points, starting with the normative reference issued by the W3C at http://www.w3.org/TR/soap/ especially, will be presented here, as they are relevant to the Web Services exposed by Alfresco.
If you have been following the trends and the discussions in the Web Services community, you will, undoubtedly, have heard about this supposedly ongoing war between proponents of SOAP and the new-fangled way of doing Web Services that is usually referred to as REST. You might also be justified in thinking that SOAP is somewhat old-fashioned, driven by industry interests, totally designed by committee, and therefore should be avoided as much as possible.
While some of the previous claims have a ring of truth to them, we are not here to tell you that you should never consider SOAP for using Alfresco-provided Web Services. It is still a reasonable technology, especially if your aim is to be able to quickly develop a new client application, as the existing toolkits hide much of the complexity from your code.
Moreover, the most recent version of SOAP, 1.2, is not so much tied to a model of distributed object calling methods on each other as it once was. However, it also pays due reverence to a model based on the exchange of resource representations, which is the underlying concept of REST. It is not entirely unreasonable to think of using SOAP 1.2 to implement a perfectly RESTful service.
In the end, the choice is yours, but if you are not interested at all in SOAP-based Alfresco Web Services, you can go straight to Chapter 6, Introducing the Web Scripts Framework.
Applications using SOAP communicate by exchanging one-way XML messages over a communication channel. Typically, but not exclusively, HTTP is used as the transmission protocol. A SOAP message, such as the following, contains one XML document, whose root element is Envelope:
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Header> <!-- application specific information --> </soapenv:Header> <soapenv:Body> <yourCustomServiceMethod xmlns="yourCustomServiceNamespace"> <parameters /> </yourCustomServiceMethod> </soapenv:Body> </soapenv:Envelope>
The Envelope element is the root element of a SOAP message, and it must conform to the following XML Schema:
http://schemas.xmlsoap.org/soap/envelope/
A SOAP Envelope element consists of:
The Header element is used to communicate information that is not application data, but is used to control the message exchange. For instance, a header can be used to send information about security or transactions. The contents of the Body element can be any valid XML fragment, and it is meant to convey application-specific information from the client to the server.
While the SOAP specification does not impose any type of semantic constraint upon the contents of the body of messages, the original purpose, and still the most common usage of SOAP, is for implementing a Remote Procedure Call (RPC) mechanism. When this is the case, such as with most Web Services exposed by Alfresco, the XML message contained in the client request will specify the names of remote procedures and the values of the parameters being passed to those procedures. Likewise, the response returned by the server will contain a representation of the return values from those procedures.
In the following code, you can find an example of calling the getStores method exposed by Alfresco (only the SOAP Body element is shown):
<soapenv:Body> <getStores xmlns="http://www.alfresco.org/ws/service/repository/1.0"> </getStores> </soapenv:Body>
A possible response from the Alfresco server is shown as follows:
<soapenv:Body> <getStoresResponse xmlns="http://www.alfresco.org/ws/service/repository/1.0"> <return xsi:type="cms:store"> <!-- returns structured datatypes --> ... </return> </getStoresResponse> </soapenv:Body>
Note that if you want to implement a different SOAP response message for your service, the response method has the same name of the request method with a suffix Response. In this specific sample, we have:
A
getStoresmethod as the request methodA
getStoresResponsemethod as thegetStoresresponse method
If you don't define a different response message for your method invocation, the SOAP protocol will send the same request message with a different timestamp as the default response. It is shown in the following figure:
 |
Another important element in the Web Services protocol stack is the Web Services Description Language (WSDL). This is the language that is used to describe the format of messages exchanged by actors using SOAP.
A server that exposes one or more SOAP-based Web Services should make available, at a documented URL, a set of WSDL documents describing such services. Using the information gathered from consulting the published WSDL documents, clients should be able to generate messages that conform to the formats required by the server in a fully automated way.
For a service that provides an RPC style of invocation, the WSDL will specify the names of the following:
The operations that the service exposes, usually corresponding to the methods on the server
The request and response messages that, together, realize a method invocation and its response
The types of the parameters and return values contained in the request and response messages
The types involved in the calls are usually defined with the help of an XML Schema Declaration (XSD) document.
In Alfresco, each service exposed through the Web Services API is defined in a separate WSDL file that contains the specifications of all the operations and data types involved.
Using a WSDL document and one of the commonly available Web Services development toolkits, it is possible to automatically generate the so-called client stub. A client stub is set of classes and methods that reflects the operations available on the server. It also relieves the client application from having to deal with the complexity of setting up a connection using the relevant transport protocol for formatting messages according to the SOAP specification and marshalling and un-marshalling native data types to and from XML.
Such toolkits are available from many programming languages, including Java, C#, PHP, and many others. Therefore, it is relatively easy to implement a Web Services client, even without knowing a lot about SOAP, as most of the complexity involved in using it is usually hidden beneath a suitable abstraction layer.
The Alfresco SDK contains, such a client stub which was mostly generated automatically from the relevant WSDLs and that will be used throughout the rest of this chapter and the following few.