Alfresco 3 Web Services

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:

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.

The format of SOAP messages

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:

• A Header element (optional)

• A Body element (mandatory)

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 getStores method as the request method

• A getStoresResponse method as the getStores response 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:

If you are developing a remote application to contact Alfresco using Java, Alfresco provides you with a precompiled Web Services client stub. The client stub allows you to invoke the Alfresco SOAP Web Services from a remote Java application, using a set of Java interfaces.

The code that makes up this client stub is available as part of the Alfresco SDK. You can download the Alfresco SDK from the same location where you can download the rest of Alfresco software. You can always browse the following web page to discover the list of files that can be downloaded for the most recent version of Alfresco Community:

http://wiki.alfresco.com/wiki/Download_Community_Edition.

Click on the Custom Installs link and look for a file to download named something like alfresco-community-sdk-3.3.zip. Once you have unpacked it, you can load the SDK as a set of projects in the Eclipse IDE, which is explained as follows, or create a project in a different IDE, and add the libraries contained in the SDK as dependencies there.

The client stub code is contained in the alfresco-web-service-client-3.3.jar. The interfaces contained therein can be used from your client Java application, as depicted in the following diagram. The purpose of the various interfaces and their intended usage will be the subject of the upcoming chapters.

To develop your own Web Service client application using the Web Services API of Alfresco, you need to configure your development environment with the Alfresco SDK.

Before starting to develop an application that uses the Alfresco Web Services, you need the following prerequisites:

The most common known IDEs used in the community are Eclipse and NetBeans. In this book, we will use Eclipse for all the examples and screenshots, but you can use any other IDEs.

The steps to set up your development environment using Eclipse IDE are as follows:

Now we have imported all the projects provided by the Alfresco SDK in to our workspace.

In order to have Alfresco source code and Java docs configured properly in Eclipse, we need to associate source code packages, related to Alfresco libraries, in the following way:

If you want Javadocs, you also need to associate Javadocs archives:

In the same way as source code packages, repeat all the previous steps for all the following Javadoc archives:

The most important projects that we will use in this book are:

SDK AlfrescoEmbedded will be used to show you how to implement a Java-backed Web Script using the Foundation Services API of Alfresco.

SDK AlfrescoRemote will be used to show you how to implement your own Web Services client stub in your custom application. In this way, we can invoke remote calls to the repository using the Content Manipulation Language (CML).

Once you have set up the SDK in Eclipse, as explained in the previous section, you can run a sample program to verify that it is working correctly. In order to perform this test, make sure that you have installed Alfresco and that it is running. We are going to assume that it is listening for an incoming connection on the host localhost, port 8080.

From within Eclipse, expand the SDK FirstWebServiceClient project, and look for the source code file named FirstWebServiceClient.java. Right-click on the file, and select Run As | Java Application. The program should start up and, after a couple of seconds, print out the following to the console window:

Content Length: 43

Now, browse the Company Home space using the Alfresco Explorer (http://localhost:8080/alfresco) and check that a file has been created there with a name like Web Services sample (long number here).