Home > SharePoint > Creating SharePoint list items with java: tutorial

Creating SharePoint list items with java: tutorial

This post completes the 2nd part of my series of “Using external business data with SharePoint”: SharePoint Web Services and Java

When I first tried to experiment with Java and SharePoint I really wondered why Microsoft didn’t invest a bit more into interoperability concerning their SharePoint platform. The potential is here: they have a market-leading product with rich Web Services. So why only support Microsoft languages? Why is there barely any Java documentation, support or examples? Or even (god forbid) a SharePoint Java library with some helper classes? I bet it would certainly attract new segments and stimulate the usage of SharePoint (or SharePoint Online) in heterogeneous IT ecosystems, what I’ve often seen in smaller companies… That would be a win-win situation for Microsoft and its customers in my opinion.

SharePoint Java Application screenshot

Tutorial introduction

In this post I will show a way to insert, update and delete SharePoint list items from Java. In case you want to build such an app from scratch, I invite you to read the three first steps of my previous tutorial that describe how to generate the Lists Web Service stub classes and how to authenticate to the Web Service. As usual, I’ve tested it with NetBeans and SharePoint Online, but it should work with MOSS 2007 and other Java IDEs. Please keep in mind that this is my take at Java and SharePoint and that there might be more efficient ways to do it, but hey, it works for me!

The challenge here will be to create a Lists request “wrapper” that will be able to do construct a basic CAML query skeleton. To better understand the structure of the request, the first stop is of course MSDN’s UpdateListItems doc. The problem is that MSDN often points fractions of the required CAML structure in their examples, but that’s not always enough, as we need to have a full SOAP sample for our Java app. What I found to be the most helpful was to fire up my browser and go to the URL of my Web Service method I was interested in. In this case, it will be UpdateListsItem, that can usually be found at sharepointsite/Lists/_vti_bin/Lists.asmx?op=UpdateListItems.

Tutorial: Creating list items from Java

In a hurry? You can download the full source code of what’s been covered until now here (GPLv2 license). Enjoy!

Here we go:

  1. Code the Lists request wrapper class. Basically this class will contain the XML SOAP request with the correct structure for the Lists Web Service. I included the imports below to avoid any ambiguity when fixing imports.
    import java.util.HashMap;
    import java.util.Map;
    import javax.xml.parsers.DocumentBuilder;
    import javax.xml.parsers.DocumentBuilderFactory;
    import javax.xml.parsers.ParserConfigurationException;
    import org.w3c.dom.Document;
    import org.w3c.dom.Element;
    import org.w3c.dom.Text;
    
    /**
     *   @author David Dudok de Wit
     *   @version 13 Feb. 2010
     */
    public class ListsRequest {
    
        private Document rootDocument;
        private Element rootDocContent;
    
        /**
         * @return the rootDocument
         */
        public Document getRootDocument() {
            return rootDocument;
        }
    
        /**
         * @return the rootDocContent
         */
        public Element getRootDocContent() {
            return rootDocContent;
        }
    }
    
    

     

  2. Code the ListsRequest constructor. This will construct a generic “New”, “Update” or “Delete” CAML request. In order to avoid errors I’ve added some requestType control checks. Moreover, to keep the constructor signature simple, I made it initialize less relevant parameters automatically (like try to insert each item of the batch operation, even if one fails).
        /**
         * This class creates a generic XML SOAP request pre-formatted for SharePoint
         * Lists web services requests (aka CAML query). What remains to be added are
         * the specific parameters (XML Elements with attributes).
         * For an example of a CAML Doc http://msdn.microsoft.com/en-us/library/lists.lists.updatelistitems.aspx
         * @param requestType Either New, Update or Delete
         * @throws Exception
         */
        public ListsRequest(String requestType) throws Exception {
            if (requestType != null) {
                if (requestType.equals("New") || requestType.equals("Update") || requestType.equals("Delete")) {
                    try {
                        Element rootElement = null;
                        DocumentBuilder docBuilder = null;
                        DocumentBuilderFactory dbfac = DocumentBuilderFactory.newInstance();
                        docBuilder = dbfac.newDocumentBuilder();
                        rootDocument = docBuilder.newDocument();
    
                        //Creates the root element
                        rootElement = rootDocument.createElement("Batch");
                        rootDocument.appendChild(rootElement);
    
                        //Creates the batch attributes
                        rootElement.setAttribute("ListVersion", "1");
                        rootElement.setAttribute("OnError", "Continue");
                        rootDocContent = rootDocument.createElement("Method");
                        rootDocContent.setAttribute("Cmd", requestType);
                        rootDocContent.setAttribute("ID", "1");
                        rootDocument.getElementsByTagName("Batch").item(0).appendChild(rootDocContent);
                    } catch (ParserConfigurationException ex) {
                        ex.printStackTrace();
                        throw (new Exception(ex.toString()));
                    }
                } else {
                    String err = "Unsupported request type";
                    throw (new Exception(err));
                }
            } else {
                String err = "Null parameters";
                throw (new Exception(err));
            }
        }
    
  3. Code the createListItem function. This function will inject a HashMap of attributes and their values into the ListsRequest CAML query, under an XML syntax.
        /**
         * Creates a SharePoint list item in the CAML format, and adds it to the rootRequest.
         * In SharePoint, this corresponds to a line in a list. The parameters given
         * here would correspond respectively to the name of the column where to
         * insert the info, and then the info itself.
         * The requestTypeElement should already be initialized before calling this
         * method.
         * XML example output:
         * < Field Name="ID" >4< Field >
         * < Field Name="Field_Name" >Value< /Field >
         * @param fields Contains a HashMap with attribute names as keys, and attributes
         * values as content
         * @return true if the item has been successfully added to the caml request
         */
        public boolean createListItem(HashMap<String, String> fields) {
            //params check
            if (fields != null && getRootDocContent() != null && this.getRootDocument() != null && !fields.isEmpty()) {
                Element createdElement = null;
                //Adds attribute by attribute to fields
                for (Map.Entry<String, String> aField : fields.entrySet()) {
                    createdElement = this.getRootDocument().createElement("Field");
                    createdElement.setAttribute("Name", aField.getKey());
                    Text attributeValue = getRootDocument().createTextNode("" + aField.getValue());
                    createdElement.appendChild(attributeValue);
                    this.getRootDocContent().appendChild(createdElement);
                }
                return true;
            }
            return false;
        }
    

     

  4. Code a higher level manager function. That’s from where we’ll authenticate, as well as decipher the error messages, and more importantly apply the business logic. This can be added in the Manager.java file. The example below is pretty basic doesn’t do basic existence checks, which means that the item will be inserted regardless if there’s already an item with the same attributes. It will however print the request in the console for debugging purposes (see the step 4 of my previous tutorial for the xmlToString function).
        /**
         * This function will insert the given item in the SharePoint that corresponds
         * to the list name given (or list GUID).
         * @param port an already authentificated SharePoint SOAP port
         * @param listName SharePoint list name or list GUID (guid must be enclosed in braces)
         * @param itemAttributes This represents the content of the item that need to be inserted.
         * The key represents the type of attribute (SharePoint column name) and the
         * value corresponds to the item attribute value.
         */
        public static void insertListItem(ListsSoap port, String listName, HashMap<String, String> itemAttributes) {
    
            //Parameters validity check
            if (port != null && listName != null && itemAttributes != null && !itemAttributes.isEmpty()) {
                try {
    
                    //Building the CAML query with one item to add, and printing request
                    ListsRequest newCompanyRequest = new ListsRequest("New");
                    newCompanyRequest.createListItem(itemAttributes);
                    System.out.println("REQUEST:"
                            + xmlToString(newCompanyRequest.getRootDocument()));
    
                    //initializing the Web Service operation here
                    Updates updates = new UpdateListItems.Updates();
    
                    //Preparing the request for the update
                    Object docObj = (Object) newCompanyRequest.getRootDocument().getDocumentElement();
                    updates.getContent().add(0, docObj);
    
                    //Sending the insert request to the Lists.UpdateListItems Web Service
                    UpdateListItemsResult result = port.updateListItems(listName, updates);
    
                    /*
                     *Printing the response in the console.
                     *If successful, the inserted item will be returned
                     */
                    System.out.println("RESPONSE : "
                            + xmlToString((org.w3c.dom.Document) (((ElementNSImpl) result.getContent().get(0)).getOwnerDocument())));
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
    

     

  5. Testing the code. Just put a few lines in main to test the whole thing. Note that if you have a column name that contains a space, you’ll have to replace the space character with _x0020_ in your attributes.
                 //Authentication parameters
                String userName = "yourusername";
                String password = "yourpassword";
                String sharePointListsWebServiceUrl = "https://yoursharepointsite.com/_vti_bin/Lists.asmx";
    
                //Opening the SOAP port of the Lists Web Service
                ListsSoap port = Manager.sharePointListsAuth(userName, password, sharePointListsWebServiceUrl);
    
                //Name or GUID (with braces) of the list
                String listName = "TempList";
    
               //Create the attributes with the format "Column name" => "value"
                HashMap<String, String> item = new HashMap<String,String>();
                item.put("Title", "Michael Drummond");
                item.put("Address", "USA");
    
                //If your column name has a space in it, replace the space with _x0020_
                item.put("Premium_x0020_customer", "1");
                Manager.insertListItem(port, listName, item);
    
  6. Updating or deleting an item is very similar; you just have to specify the “ID” of the List item (which can be extracted by reading the list first), just like we did in the previous step with the attributes.

 

That’s it!
Keep in mind that this is a simple example that’s not guaranteed to be appropriate for a production environment. For example, It would be interesting to tweak the code to do allow batch inserts/deletes as well as a transaction system that would be able to cache the requests in case of failure. I hope you found this post helpful.

  1. August 6, 2010 at 20:32

    David,

    I am trying to perform an AddAttachment method execution in Java. When I create what I think should be the valid HTTP/XML request, I get an HTTP 400 Bad Request, unfortunately with no specific details as to what it dislikes.

    Would you happen to have/be able to post a sample of a valid HTPP Request for the AddAttachment method?

    Thanks in advance.

  2. Robin
    September 15, 2010 at 09:23

    Really helpful, thanks a lot.

  3. Tom
    March 25, 2011 at 22:17

    I must say, you have done an awesome job and put a lot of effort in writing this code. Being a newbie, I was so much frustrated since I could not find any good resources on java web-service clients for Sharepoint web-services and this article was the ice-breaker for me.

    Thank you so much once again!

    Hoping, you could post more of these article in your leisure time(like examples of adding attachments to sharepoint etc.)

    Best Regards,
    Tom

  4. Carlos Alvares
    May 2, 2011 at 19:00

    Hi there,

    Awesome article, it help’s me a lot to forward my project.
    But now I have got this exception:

    java.lang.Exception: Error: com.sun.xml.ws.wsdl.parser.InaccessibleWSDLException: 2 counts of InaccessibleWSDLException.

    java.io.IOException: Server returned HTTP response code: 401 for URL: http://contosodemo/BIdemo/_vti_bin/Lists.asmx
    java.io.IOException: Server returned HTTP response code: 401 for URL: http://contosodemo/BIdemo/_vti_bin/Lists.asmx?wsdl

    What can I do??

    Thanks once again,
    Carlos ALvares

  5. Ming
    December 9, 2011 at 07:14

    Hi, David:
    I am trying out your codes. Can you tell me where are ListsSoap and Lists classes?

    Thanks,

  6. Aniruddh
    March 8, 2012 at 07:04

    Awsome job David but can you please tell me how to implement LIstSoap LIst and Manager class

  7. Vijayakumar B
    April 30, 2012 at 19:15

    Hi David
    Thanks for the excellent article. But can you please let us know to which jar set ListsSoap belongs to and how to get it

  8. Omkaaraa
    May 9, 2012 at 08:51

    David,

    I have to fetch document ID or unique ID of stored documenet, based on URL. How to use Query and QueryOption for that? Or is there any other way to get these ID’s?
    I tried, but no luck.

    Regards,
    Omkaaraa

  9. Alexey
    July 20, 2012 at 20:44

    hi David,

    can you please share the sources somewhere else like dropbox since megaupload is down?

    Thanks in advance,
    Alexey.

  10. Zack
    August 16, 2012 at 16:54

    I am trying to figure out if there is a way to manage sharepoint permissions with a java integration

  11. Nick
    December 12, 2012 at 10:14

    can you share the source code that others can down lit? thanks.

  12. Kiran
    April 3, 2013 at 08:05

    hi David,

    Awsome tutorial David but can you please tell me how to add ‘Start date’ of LIst in UTC date format.

    Thank u,

  13. vkofman
    January 18, 2014 at 00:11

    Hi the link to download the source code is not working anymore. Can you please let me know how to download the sample code this tuoria?

  14. March 26, 2014 at 16:19

    Hi David,
    I created a Java Client for SharePoint Web Service that uses NTLM Authentication. My Code is working fine but the problem is that, my Java code is able to authenticate with Incorrect credentials as well.

    Note:- At First run of the Java Code i used Correct Credentials.

    As i am novice to Sharepoint, I’m not sure Whether SharePoint is caching the Correct Credentials somewhere.

    Please suggest.

  1. February 16, 2010 at 00:06
  2. March 17, 2010 at 20:38

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: