Web Service Samples for Java

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Web ServicesWeb Service Samples
Back to Alfresco Content Management Web Services

Java Samples

There are a number of Java web service samples that can be found in the Alfresco source distribution within the package org.alfresco.example.webservice.sample.  These samples demonstrate a number of simple web service use cases.

• WebServiceSample1 (GetStores.java) - This sample shows how to authenticate a user, provides an example of a CallbackHandler and shows how to get a list of the available stores.
  
• WebServiceSample2 (Query1.java) - This sample shows how to execute simple searches and navigate the results using the Repository Web Service.
  
• WebServiceSample3 (ContentReadAndWrite.java) - This sample shows how content can be created, read and updated using the Content Web Service.
  
• WebServiceSample4 (CMLUpdates.java) - This sample shows how to construct and execute CML queries using the Repository Web Service.
  
• WebServiceSample5 (CheckOutCheckIn.java) - This sample shows how to check documents out, check them back in and then view the version history using the Authoring Web Service.
  
• WebServiceSample6 (Categories.java)- This sample shows how content can be queried for using categories using the Classification Web Service (This use case was provided by a member of the community)
  

More samples can be found in the Alfresco SDK.

If you have a specific use case that you feel would make a useful sample then please let us know.

Starting a Session

Before we can communicate with any Alfresco web service we must authenticate the current user by starting a session.  This can be achieved using the startSession method found on the Authentication Web Service.

The method startSession is provided with a user name and password and, if authentication is successful, returns a ticket.  This ticket can then be used when calling other web service methods.

  

   // Get a reference to the 
   AuthenticationServiceSoapBindingStub authenticationService = 
      (AuthenticationServiceSoapBindingStub) new AuthenticationServiceLocator()
      .getAuthenticationService();
        
   // Start the session
   AuthenticationResult result = authenticationService
                                 .startSession(userName, password);
   String ticket = result.getTicket();

Once all work has been completed a call to endSession will invalidate the current session.

   // End the session
   authenticationService.endSession(ticket);

Using the Ticket

Calls to all Alfresco web service methods must have the WS security information in header.  This ensures that only authenticated users are able to access the web service API.

In the samples provided with the source distribution the WS Security information is provided as a XML deployment definition, an example of which is shown below.

   <deployment xmlns='http://xml.apache.org/axis/wsdd/' 
               xmlns:java='http://xml.apache.org/axis/wsdd/providers/java'>
      <transport name='http' 
                 pivot='java:org.apache.axis.transport.http.HTTPSender'/>
      <globalConfiguration >
         <requestFlow >
            <handler type='java:org.apache.ws.axis.security.WSDoAllSender' >
               <parameter name='action' value='UsernameToken'/>
               <parameter name='user' value='ticket'/>
               <parameter name='passwordCallbackClass'
                value='org.alfresco.example.webservice.sample.WebServiceSample1'/>
               <parameter name='passwordType' value='PasswordText'/>
            </handler>
         </requestFlow >
      </globalConfiguration>
    </deployment>

The passwordCallbackClass is then responsible for providing the ticket when the web service methods are called.  It must implement CallbackHandler which has the single method handle.

See below for an example implementation of handle.

   /**
     * The implementation of the password callback used by the WS Security
     * 
     * @see javax.security.auth.callback.CallbackHandler#handle(javax.security.auth.callback.Callback[])
     */
    public void handle(Callback[] callbacks) 
                throws IOException, UnsupportedCallbackException
    {
       for (int i = 0; i 

In order that the deployment information and callback handler are used when issuing a web service method call the client web service classes must be provided with the deployment information when they are created.  The following snipit shows how to create a reference to the repository service with this in mind.

   // Create the respository service, adding the WS security header information
   EngineConfiguration config = new FileProvider(
            new ByteArrayInputStream(
                WebServiceSample1.WS_SECURITY_INFO.getBytes()
                )
            );
   RepositoryServiceLocator repositoryServiceLocator = 
                            new RepositoryServiceLocator(config);        
   RepositoryServiceSoapBindingStub repositoryService =
   (RepositoryServiceSoapBindingStub)repositoryServiceLocator.getRepositoryService();