47,99 €
Mehr erfahren.
- Herausgeber: Packt Publishing
- Kategorie: Wissenschaft und neue Technologien
- Sprache: Englisch
Alfresco 3 is the leading open source enterprise content management system that offers powerful features for interacting with the content in its repository from outside the system. These include the support for the Content Management Interoperability Services (CMIS) implementation, reusable web scripts, and a Web Services API.
This is the first book to show you how to use Web Services in Alfresco. Packed with examples, you'll learn how to build applications using Alfresco remote APIs based on SOAP and REST. You'll see how to use different APIs and bindings such as WebServices, WebScripts, and CMIS.
Alfresco 3 Web Services starts off by showing you the services exposed by the Alfresco Web Services API, and how the API fits into the Alfresco software architecture.You learn to develop your application firstly by setting up and testing your Java development environment using the Alfresco SDK in Eclipse IDE and secondly by associating the Alfresco source code and Javadocs in Eclipse.With the help of real world practical examples, you learn how to do things like create, sort, and call Web Scripts, and invoke remote calls to Alfresco repository. To get the most from the Web Services API, you need to know about the basics of the Content Manipulation Language (CML), and the book takes you through this.Examples such as the bookshop application show you how to sign in, change user sessions, get, remove and change public and private associated contents, manage a cart for your e-commerce application, and so on.Next, by implementing a Microsoft .NET application using the Alfresco Web Services API, you see how to perform operations against the repository from your .NET application.The book provides you with REST and SOAP concepts, their comparison, basics of the FreeMarker language, Atom Publishing Protocol, JavaScript controllers, and the Apache Chemistry project.By the end of this book, you will be able to put together your knowledge about CMIS and the Apache Chemistry toolkit to develop a complete working application that uses Alfresco, via CMIS, as a back-end storage. Last but not the least, this book also covers the WebServices security profiles— the best practices for Web Services to promote better interoperability.
Das E-Book können Sie in Legimi-Apps oder einer beliebigen App lesen, die das folgende Format unterstützen:
Seitenzahl: 434
Veröffentlichungsjahr: 2010
Ähnliche
Table of Contents
Alfresco 3 Web Services
Alfresco 3 Web Services
Copyright © 2010 Packt Publishing
All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.
Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the authors, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.
Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.
First published: August 2010
Production Reference: 1110810
Published by Packt Publishing Ltd.
32 Lincoln Road
Olton
Birmingham, B27 6PA, UK.
ISBN 978-1-849511-52-0
www.packtpub.com
Cover Image by John M. Quick ( <[email protected]> )
Credits
Authors
Ugo Cei
Piergiorgio Lucidi
Reviewers
Adrián Efrén Jiménez Vega
Amita Bhandari
Acquisition Editor
Steven Wilding
Development Editor
Mayuri Kokate
Technical Editor
Vishal D Wadkar
Copy Editor
Leonard D'silva
Indexer
Hemangini Bari
Editorial Team Leader
Aanchal Kumar
Project Team Leader
Lata Basantani
Project Coordinator
Jovita Pinto
Proofreader
Lesley Harrison
Graphics
Geetanjali Sawant
Production Coordinator
Aparna Bhagat
Cover Work
Aparna Bhagat
About the Authors
Ugo Cei is a solutions delivery manager at Sourcesense, Italy. He has over 20 years of experience in the IT sector. His areas of expertise include web application development, content management systems, database, and search technologies. He has a Ph.D. in Engineering from the University of Pavia, Italy. Ugo is a long-time active contributor to numerous open source projects and a member of the Apache Software Foundation (ASF).
Besides his interest in computer-related matters, Ugo is a passionate photographer. He sometimes dreams of leaving the IT field to pursue his passion full-time, and travel the world with a camera.
I would like to thank the employers at Sourcesense, Italy for introducing me to Alfresco and giving me the opportunity and the time to work on this book.
Piergiorgio Lucidi is an open source product specialist and a certified Alfresco trainer at Sourcesense. Sourcesense is a European open source systems integrator providing consultancy, support, and services around key open source technologies. Piergiorgio has worked as a software engineer and developer for six years in the areas of Enterprise Content Management (ECM), system integrations, web and mobile applications. He is an expert in integrating ECM solutions in web and portal applications. He contributes to the Alfresco Community forum regularly supporting both newbies and expert users.
Piergiorgio is a project leader and committer of the JBoss community and contributes to some of the projects around the portal platform. He is a speaker at the conferences dedicated to Java, Spring framework, and open source products and technologies. He is an affiliate partner at Packt Publishing, and writes and publishes book reviews on his website Open4Dev (http://www.open4dev.com/).
I would like to thank my colleague—Jacopo Franzoi for helping us to write the chapter of the book on the Microsoft .NET framework topic.
My special thanks to my colleague—Ugo Cei for giving me the opportunity to write my first book with him. I would like to thank all my team members at Sourcesense for improving and fixing my writing style. I would also like to thank my girlfriend—Barbara, who encouraged me during the making of this book.
About the Reviewers
Adrián Efrén Jiménez Vega works at the Center of Information Technologies (CTI) of the University of the Balearic Islands, in Mallorca (Spain). For four years, he has built and deployed various applications based on Alfresco. Since registering in the Alfresco Spanish forum approximately two years ago, he has dedicated time and openly shared his experience posting more than 600 messages, and contributed many practical solutions and useful hints for members of the community. The 'mini-guides' that he developed are now widely used and referenced among developers in Spain and Spanish speaking countries.
He won the "Alfresco Chumby Awards for Community Achievement" in November 2008. He has also won the "Web Script Developer Challenge" with a Web Script solution to limit the space for users, including e-mail notification. He has also worked as technical reviewer for the book Alfresco 3 Enterprise Content Management Implementation (Packt Publishing) in 2009.
I would like to thank all those people who made my participation possible in this project. In particular, my parents (despite the distance), my sister, and my friends at CTI.
Amita Bhandari has hands-on experience in Alfresco CMS, Java, J2EE, object-oriented Architecture, and Design Patterns. Her expertise lies in implementing J2EE technologies (JSP, Servlets, EJB, and MVC Frameworks) to develop Enterprise web applications. She has worked with various design patterns such as Struts, Spring, and Hibernate.
Tranformations of XML files into various formats, advanced workflows, Web Scripts along with experience in server-side configuration, administration, Web Services, and application deployments are really what make her a sought after authority on the subject. She has worked with clients in media and gaming, healthcare, and e-governance. She has experience of training students in Java and advanced Java technologies.
She is a senior consultant at CIGNEX. She holds a Masters in Computer Applications from Rajasthan University, India. She is also the co-author of Alfresco 3 Enterprise Content Management Implementation, which was published by Packt Publishing.
I would like to thank all the people who made my participation possible in this project. In particular, my parents, my spouse, my brother, my friends, and especially, Munwar Shariff and Manish Sheladia for their help and contribution.
Preface
During recent years, we at Sourcesense supported our customers by implementing different system integrations based on open source technology. At Sourcesense, our main goal is to help our customers to choose the best approach for adopting open source.
Sourcesense offers consultancy, integration, high-level support, and training in enterprise-ready open source technologies across four business areas: Enterprise Content Management, Enterprise Search, Business Intelligence, and Application Lifecycle Management. We have offices in four European cities—London, Amsterdam, Rome, and Milan and we are able to offer local, co-developers and near-shoring solutions.
Sourcesense is well regarded in the open source community, contributing to many OS projects through the Apache foundation and JBoss community; we actively look for contributors and committers to hire, and we encourage them to keep contributing to the OS ecosystem. Sourcesense is also one of the exclusive training partner of Alfresco, we are the only one offering official training in the UK, Italy, and Netherlands.
Alfresco 3 is one of the most versatile open source Enterprise Content Management (ECM) platforms. This is a real open source alternative to commercial product such as Microsoft SharePoint and EMC Documentum. It is also very well designed and suitable to be customized and extended. The open source adoption allows developers to contribute on the project and that's why you can find more than 240 extensions in the Alfresco Forge.
This book shows you how to build applications on top of Alfresco using all the Web Service interfaces exposed by the product. Alfresco provides services to client applications for manipulating content and for performing additional operations to manage the content lifecycle.
We start discussing about the Web Services API of Alfresco that is based on the SOAP protocol. Then we describe how to extend the REST API of Alfresco using the Web Scripts Framework. Finally, we explain the new specification named Content Management Interoperability Services (CMIS), it is dedicated to improve interoperability between content management systems. Alfresco was one of the first ECM platforms to provide a complete CMIS implementation. We hope that it could be useful for you to learn this new standard and how you can use it with any CMIS-compliant repository.
What this book covers
Chapter 1, Introducing the SOAP Web Services introduces the basic information about Web Services and the specific Alfresco Web Services implementation. It also explains how to set up your development environment before starting to use the Alfresco Web Services API.
Chapter 2, Creating and Modifying Content includes an overview of the Content Manipulation Language (CML) of Alfresco. It also describes how to use the CML language for manipulating content using the Alfresco Web Services API. This chapter also teaches you how to search contents in the repository.
Chapter 3, Collaboration and Administration covers operations for collaborative editing. You'll also learn how to manage repository actions, rules, and users.
Chapter 4, A Complete Example describes an example of a bookshop application implemented using the Web Service Client stub provided by Alfresco. This chapter shows you how to implement basic operations to manage users, books, and the cart for orders.
Chapter 5, Using the Alfresco Web Services from .NET teaches you how to use the Alfresco Web Services API from your Microsoft .NET application. It also shows you how to configure your development environment using the open source IDE SharpDevelop.
Chapter 6, Introducing the Web Scripts Framework takes you through an overview of REST concepts and also provides you a step-by-step example to start developing your first Web Script.
Chapter 7, Templating with Freemarker gives the basic concepts about Freemarker discussing about how to build your view template. It also includes an overview about the Alfresco Template Node API and the JSON format.
Chapter 8, Writing a Web Script Controller in JavaScript and Java covers how to implement a Web Script using a JavaScript controller. It describes all the root objects available in the JavaScript API of Alfresco and how to perform basic operations to manage the content. It also shows you how to pass values to the view template. It also explains how to implement Web Scripts in Java, if you need more powerful features for your functionality.
Chapter 9, Putting it All Together shows you a complete example of how to implement a bookshop application using the Web Scripts Framework.
Chapter 10, Overview of CMIS focuses on the Content Management Interoperability Services (CMIS) specification. You'll learn the history of this new standard and its main objectives. You'll also learn the available protocol bindings and the CMIS domain model.
Chapter 11, The CMIS AtomPub Binding introduces a section about how to perform basic operations using the REST Binding of CMIS.
Chapter 12, Developing a CMIS Client Using Apache Chemistry explains how to implement a CMIS client using the REST binding. It describes with a complete example how to perform basic operations on contents and how to search contents in the repository using Apache Chemistry.
Chapter 13, The Web Services Binding describes how to implement your client application using the CMIS SOAP binding. This chapter starts showing you how to retrieve all the WSDLs and how to generate your client stub using Apache CXF. It also explains how to perform basic operations on contents using the SOAP binding of CMIS.
Chapter 14, A Complete CMIS Client Application shows you a complete example of a Wiki application that stores contents in a CMIS-compliant repository.
At the end of the book, you will find an Appendix about the CMIS query language. In this section, you'll find reference information about how to build queries to search contents using CMIS. Specifically, in this section, you'll learn the CMIS relational view, clauses, operators, and predicates.
What you need for this book
The following is a list of the software that you will need for this book:
Who this book is for
If you are a web developer who wants to build business applications on top of Alfresco, then this is the book for you. It is intended to be a complete overview to help developers choose a specific API with related method invocations.
Conventions
In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning.
Code words in text are shown as follows: "A CML operation is defined with an XML complexType and its sequence of properties."
A block of code is set as follows:
When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:
Any command-line input or output is written as follows:
New terms and important words are shown in bold. Words that you see on the screen, in menus, or dialog boxes for example, appear in the text like this: "Right-click on the Package Explorer, and click on Import...".
Note
Warnings or important notes appear in a box like this.
Tip
Tips and tricks appear like this.
Reader feedback
Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of.
To send us general feedback, simply send an e-mail to <[email protected]>, and mention the book title via the subject of your message.
If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com or e-mail <[email protected]>.
If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.
Customer support
Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.
Note
Downloading the example code for the book
You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.
Errata
Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/support, selecting your book, clicking on the errata submission form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded on our website, or added to any list of existing errata, under the Errata section of that title. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.
Piracy
Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.
Please contact us at <[email protected]> with a link to the suspected pirated material.
We appreciate your help in protecting our authors, and our ability to bring you valuable content.
Questions
You can contact us at <[email protected]> if you are having a problem with any aspect of the book, and we will do our best to address it.
Chapter 1. Introducing the SOAP Web Services API
One of the most adopted ways to manipulate content in the enterprise content management world is to use Web Services. In this chapter, you will learn about some aspects of the specification of Web Services. You will also get an overview of Alfresco and an in-depth description of the Alfresco-specific Web Services implementation.
You will learn about the Alfresco software architecture, so that you understand how Alfresco exposes the Web Services API in a better way. You can find many other implementations of Web Services outside this context, but we will focus only on the Alfresco-specific implementation.
So, in this chapter, you will learn the following:
Web Services
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.
Web Services in Alfresco
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.
Introducing SOAP
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.
SOAP vs. REST
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.
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:
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):
A possible response from the Alfresco server is shown as follows:
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:
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:
The Web Services Description Language
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 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.
Using Alfresco Web Services
Provided you can access an instance of Alfresco running on the server host and listening on TCP port, you can retrieve all the WSDLs for the Alfresco Web Services by pointing a browser to the URL for each service, as detailed in the following table.
Each service provides a set of operations related by a common purpose, so that you may use only the ones that you are interested in:
Service name
Purpose
URL
AccessControlService
Manage permissions
http://host:port/alfresco/api/AccessControlService?WSDL
ActionService
Execute custom actions and rules
http://host:port/alfresco/api/ActionService?WSDL
AdministrationService
Manage users and groups
http://host:port/alfresco/api/AdministrationService?WSDL
AuthenticationService
Login and access session tickets
http://host:port/alfresco/api/AuthenticationService?WSDL
AuthoringService
Allows collaboration between users
http://host:port/alfresco/api/AuthoringService?WSDL
ContentService
Read and write content
http://host:port/alfresco/api/ContentService?WSDL
ClassificationService
Manage categories
http://host:port/alfresco/api/ClassificationService?WSDL
DictionaryService
Manage content models
http://host:port/alfresco/api/DictionaryService?WSDL
RepositoryService
Navigate, search, and manipulate nodes.
http://host:port/alfresco/api/RepositoryService?WSDL
Besides retrieving the WSDL documents online, using the URLs from the previous table, you can also find copies of the WSDLs as files in the Alfresco source tree. You can download a copy of the Alfresco source from the Subversion repository, as explained in the wiki page at http://wiki.alfresco.com/wiki/Alfresco_SVN_Development_Environment. The WSDL files can be found under root/projects/remote-api/source/wsdl in your copy of the source tree. In this folder, you can also find all the WSDL files related to the Web Services binding of the CMIS implementation of Alfresco that will be described in Chapter 13, The Web Services Binding. Another location where you can find a copy of the WSDL documents is inside the Alfresco SDK, in the lib/remote/wsdl folder. Downloading and installing the Alfresco SDK is the subject of the next section.
Using the Alfresco Web Services client SDK
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.
Setting up the Alfresco SDK
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:
Alfresco SDK Project
Library
Source code package
SDK AlfrescoEmbedded
alfresco-repository-3.3.jar
alfresco-repository-src.zip
SDK AlfrescoEmbedded
alfresco-core-3.3.jar
alfresco-core-src.zip
SDK AlfrescoEmbedded
alfresco-remote-api-3.3.jar
alfresco-remote-api.zip
SDK AlfrescoEmbedded
alfresco-web-client-3.3.jar
alfresco-web-client-src.zip
SDK AlfrescoRemote
alfresco-web-service-client-3.3.jar
alfresco-web-service-client-src.zip
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:
Alfresco SDK project
Library
Archive package
SDK AlfrescoEmbedded
alfresco-repository-3.3.jar
alfresco-repository-doc.zip
SDK AlfrescoEmbedded
alfresco-core-3.3.jar
alfresco-core-doc.zip
SDK AlfrescoEmbedded
alfresco-remote-api-3.3.jar
alfresco-remote-api-doc.zip
SDK AlfrescoEmbedded
alfresco-web-client-3.3.jar
alfresco-web-client-doc.zip
SDK AlfrescoRemote
alfresco-web-service-client-3.3.jar
alfresco-web-service-client-doc.zip
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).
Testing the Web Services client
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:
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).
Note
If your server is not listening on port 8080 of the localhost, which is the default port, you need to modify the file source/alfresco/webserviceclient.properties, contained in the sample, and change the value of the repository.location property according to your server's hostname and port.
Summary
In this chapter, we have given you an overview of Web Services and specifically discussed how the Web Services API is integrated in the Alfresco software architecture. In the second section, we saw an overview of the SOAP protocol and the basics behind the client/server paradigm. Then we introduced the services that are exposed by Alfresco and where you can retrieve all the available WSDL files.
Finally, we discussed how to set up and test your Java development environment using the Alfresco SDK in Eclipse IDE. In this way, you can start to develop your application using all the dependencies described. You also learned how to associate Alfresco source code and Javadocs in Eclipse.
In the next chapter, you will learn how to remotely perform operations in the Alfresco repository using the Web Services API.
Chapter 2. Creating and Modifying Content
In this chapter, you will learn how to perform operations on nodes using the Alfresco Web Services API. We will start by introducing the Content Manipulation Language (CML), which is the language used to invoke operations against the repository. Then, we will discuss the operations that you can use to manage your content. Specifically, you will learn how to perform the following operations:
The Content Manipulation Language (CML)
Alfresco has created the Content Manipulation Language (CML) to provide a mechanism to perform multiple statements in the repository using a unique SOAP message. This is an XML-based language defined with an XML Schema available at the following address:
http://svn.alfresco.com/repos/alfresco-open-mirror/alfresco/HEAD/root/projects/remote-api/source/wsdl/cml.xsd.
You can also find it in the Alfresco SDK, at this path: Alfresco SDK/lib/remote/wsdl/cml.xsd.
As the CML is based on XML, it can easily be represented in other programming languages. This means that each statement will be declared with an XML snippet that must conform to the XML schema of the CML language. One of the operations that we will start to describe later is the CMLCreate operation. This operation allows you to create a new node in the repository, and it is declared in the cml.xsd file as a statement, in the following way:
A CML operation is defined with an XML complexType and its sequence of properties. For each request of a CMLCreate, the client stub will generate the following XML code to perform the operation:
As you can see, in this sample message, we have a unique operation of type create. This operation must conform to the XML Schema of the CML language, as declared in the previous namespace as http://www.alfresco.org/ws/cml/1.0.
The statements element allows you to encapsulate many CML statements in a unique request message. If you want to create two nodes, then the client stub will generate an array of CMLCreate operations in this way:
CML allows you to perform multiple operations defining an array for each type of operation. You can also perform different types of operations in the same request.
Note
You can find more information about CML at the following URL: http://wiki.alfresco.com/wiki/CML.
Setting up the Java classpath
Before starting the implementation of your client, you need to configure your Java project properly. You can follow two main different approaches for this, namely, using the precompiled Alfresco Web Service Client or using a third-party implementation.
Using the precompiled client
If you would like to use the SDK AlfrescoRemote, you can use the precompiled Web Service Client provided by Alfresco. This is the adopted approach for the book. This project must be selected as one of your required projects for your build path. In this way, you are going to use all the dependencies needed for the Alfresco Web Services Client.
We are assuming that you have correctly set up the SDK in Eclipse, as shown in the previous chapter. In order to configure your Java project correctly in Eclipse, you need to follow these steps:
Using third-party frameworks
Alternately, if you don't want to use the precompiled Web Service Client, you can generate your client stub getting all the WSDLs exposed by Alfresco. These are described in the previous chapter. Each WSDL file can be used with any framework dedicated to implement Web Services, for instance, Apache CXF or Apache Axis.
The final artifact of the framework is the client code that you can embed in your project to invoke remote methods using the Alfresco Web Services API. This means that you will have specific dependencies in your Java Build Path without using the SDK AlfrescoRemote project. But all the methods and objects are the same as we described in this chapter.
