All About Interop : Exchange

Connecting to Exchange using JAX-WS, part 1

DotNetInterop — Tue, 29 Jul 2008 21:52:00 GMT

Yes, it is possible to Connect to Exchange using JAX-WS

The fear and trepidation I had when considering the effort to connect a Java application to Exchange Server 2007 was well founded. It wasn't easy. I'm going to spoil the ending and tell you, yes, it is possible to connect Java apps to Exchange Server via Web services, and you can do it securely and with good performance and reliability. But it took some starts and stops to make it happen.

Warning: Old Guy Reminiscing Ahead

Back a few years, I was a technical marketing guy for the Microsoft platform, and my main role Was talking to customers. One of the things I talked with customers about often, was interop. Pretty much every customer I talked to already had a signficant investment in information technology, they had a strategy that was in place and working, they had systems in place, working. They had off-the-shelf apps, they had some custom-built apps, and they had skillz. They were looking to make adjustments, to evolve their systems, to improve. It reminded me of the principles of Agile Development.

Do you remember XP? Do you remember how trendy that was, like 3 or 4 years ago. Everyone was talking about XP, everyone was looking to apply XP principles into their approaches. That seems a long time ago. XP is so 2004.

The approach that companies took with their information systems architecture was something like what developers did in a different domain with XP. Lots of little iterations, constant improvement, and steadily you get closer to your goal.

I remember talking to customers about web services technology, about using standard XML-based protocols to enable better connections between disparate information systems. Yes, Virginia, this was actually a theme of my conversations back only a few years ago. Now it seems so obvious. Now that everything speaks XML and interconnection is fairly easy, the wisdom of using standard protocols to gain efficiencies in IT is apparent. But only a short time ago this issue was not so clearly understood.

To make my case that web services and XML based protocols were the future, I'd show customers the investments that Microsoft was making into them. I'd tell them about all the standards was Microsoft working on. But the thing that customers wanted was hard evidence - not standards or papers. They wanted proof of XML usage in Microsoft products. So I'd talk about all the XML-based protocols that were already in the existing Microsoft systems they had: the web services libraries in the .NET Framework, the tooling in Visual Studio (but these were fairly obvious). The XML shredding capability that was introduced in SQL 2000 and improved in SQL 2005. Actually with the FOR XML clause you can do some pretty nifty things with the data that is already in your database. The MSXML component - now sort of just accepted as part of the landscape, a key, if almost forgotten enabler of AJAX - but 6 or 7 years ago it was undergoing rapid development.

These are all pretty good examples of Microsoft's investment in XML and WS-*. But one of the things that really surprised people was the web services capabilities we were introducing into Office (with WordML and ExcelML and so on), and the Exchange Server.

Exchange Server 2007 and Web services

Exchange Server 2003 had some limited web services capabilities. With Exchange Server 2007, Microsoft delivered an email and collab server that exposed all of its features through standard web services interfaces. Today if you have an Exchange Server, you can point your browser to http://my.exchange.server.com/ews/Exchange.asmx and get a WSDL for the server. Wow. That is pretty cool.

Standards are standards, and complying to a standard doesn't guarantee interop. If you are designing a web services interface, you can get better interop by keeping your WSDL fairly simple, and constraining your interface definitions to avoid some of the more esoteric nooks and crannies of the XML Schema spec. This is advice we've all been following for years. It works.

The problem with that advice is that it does not work if the information systems at the end of the wire are not simple, or if the requirements are not simple. For example, if you want WS-Addressing or delegated security, things can get complicated. And, similarly, Exchange Server is not simple. It stores lots of different types of things (email messages, contacts, tasks, notes, calendar entries, requests, resent items, recurrences, mime content type, cancellations, suggestions for new times, and so on). And then it compounds that complexity by adding in an unstructured aspect - document attachments and other unstructured data. Then there is stuff like impersonation, delegation (your admin assistant can update your calendar), out-of-office messages, and so on. It's pretty rich.

With all that capability, necessarily, the interface to Exchange is not going to be simple. Look at the user interface in Outlook - it is pretty rich. And the same is true with the network interface on the wire, described in the WSDL.

As a result, the WSDL for Exchange is complicated. It's big. It's got lots of nested structures. There are unions and restrictions and headers and bodies. It breaks all the rules for designing schema with interop in mind.

Anyway, who needs web services, right? We can use WebDAV!

Interop and the Exchange Server web services interface

First decision: which web services library to use? My first thought was to use the tried-and-true Apache AXIS 1.4 library that I had been depending on since 2006. It wasn't THAT old, and it worked for all the other interop tasks I had tried it on. It connected to .NET systems using ASMX or WCF. It was simple. I knew the tools.

My first step was to grab the Exchange.wsdl, the types.xsd and the message.xsd. I knew that I needed to add a service definition to the end of the Exchange.wsdl file, because most WSDL compilers want it:

   <wsdl:service name="ExchangeServices">
     <wsdl:port name="ExchangeServicePort" binding="tns:ExchangeServiceBinding">
       <soap:address location="https://myexchange.company.com/EWS/Exchange.asmx"/>
     </wsdl:port>
   </wsdl:service>

</wsdl:definitions>

But very early the work with AXIS 1.4 was hitting roadblocks. That library generated source code that did not compile. It choked on quite a few things. Other people have walked this path but custom modifications to the generated code did not sound like fun to me. I quickly decided that I'd need to move to something else.

My next idea was to move to AXIS2, which, coincidentally, is also at version 1.4. Now why they chose to call it "AXIS2 1.4" instead of "AXIS 2.4" is beyond me. There is a significant breakage in back-compatability with the move to AXIS to AXIS2, but still the version numbers are very confusing.

AXIS2 introduces a number of changes over AXIS (1). The AXIS guys improved the XML schema support, for one. Also, they made the XML serialization engine pluggable, so you can use the built-in simple library (called ADB), or you can switch to use JiBX or XMLBeans.

As with AXIS1, I ran the Exchange WSDL through the AXIS2 tools to generate the client-side proxies. This time, the code actually compiled. I was pleased to see that there was just one giant Java file generated for the entire Exchange interface. In AXIS 1.4, there was a whole series of files, 447 of em. Too many, thought I. But AXIS2 v1.4 generated just one file. Cool!

And it was a big one. Opening the file in emacs - emacs asked me, "are you sure you want to open this file? it's really big!" Seriously. And compiling that single file with javac, I actually got a heap overflow. Wow! That's a big file. I just used the -X heap magic incantations on that file and I was able to compile it.

I wrote up a simple proof of concept Java class that used the generated AXIS stub classes to connect to Exchange Server. When I ran the code, I got a failure: "required attribute localTraversal is null" I had no idea where that was leading me. I searched in the WSDL and schema for Exchange but couldn't find any elements or attributes by that name. I considered ripping open the AXIS2 source code to try to troubleshoot it. Wasn't real excited about that prospect. I had no idea where that was leading me.

My next step was to try the XMLbeans serialization option in AXIS 2. With this, I was back to generating ~ 400 Java files. But I didn't care, as long as the interop worked. And I had to update my client application code, because switching from ADB to XMLBeans necessitates a change in the programming model. I didn't care, though. Interop! (The things I do for interop!)

The AXIS2 + XMLbeans combo was looking promising, but also failed, this time with

java.lang.ClassCastException: org.apache.xmlbeans.impl.values.XmlComplexContentImpl cannot be cast to com.microsoft.schemas.exchange.services._2006.types.Folder
IdType

This is apparently a common error, if there is a duplication in classes. I don't think I had that. I keep a clean workspace. Some of the XMLBeans people suggested on forums to upgrade to the later version of XMLBeans. There was no better suggestion I found. The AXIS2 library bundles XMLBeans 2.3.0, but XMLBeans standalone was at v2.4.0. So I downloaded 2.4.0, and tried to manually compile the schema with the scomp tool.

c:\apache\xmlbeans-2.3.0\bin\scomp -out GeneratedTypes.jar contract\ExchangeServices.wsdl  -compiler c:\sunjdk\bin\javac.exe

But, then, another runtime exception:

Exception in thread "main" java.lang.NoClassDefFoundError: com/microsoft/schemas/exchange/services/_2006/types/FolderIdType
        at ExchangeClient.Run(ExchangeClient.java:161)
        at ExchangeClient.main(ExchangeClient.java:217)
Caused by: java.lang.ClassNotFoundException: com.microsoft.schemas.exchange.services._2006.types.FolderIdType
        at java.net.URLClassLoader$1.run(Unknown Source)

It was one problem after another. Also, I had found the documentation and examples to be completely lacking for AXIS2. I couldn't find anyplace that gave me any hints. Why was it so hard to find information on this thing? And why did I have to use Class.Factory.Create(); instead of just calling new Class(). How dumb is this? And finally, there were 59 JAR files I needed to reference for AXIS2. That's what the doc told me. Commons-logging, xmlbeans, axis-api, axis-rt, corba, neethi, axiom, anogen, and on and on. I don't even know what those things are. The whole thing felt very... messy. I've already experienced JAR Hell and I don't want to go back there. I'm sure each one of those jars is required, but AXIS2 *could* be a little more seamless. As it is, it feels like a science project.

Ok, time to switch horses. The AXIS Stuff was not giving me joy. My next attempt would be to use JAXWS.

With JAXWS, there is one runtime JAR. One. The code-gen produces... a JAR. How refreshing! I don't need 400 class files. I can just reference a JAR. (Yes, I know there are 400 classes inside the jar. I don't care. It's a single jar). Hmm, someone ought to tell the AXIS project about this upstart JAXWS. The stub classes get generated and compile nicely. (small victory, cross fingers and hope for more). I am starting to like JAXWS.

The programming model exposed by JAXWS-generated client-side classes is a little different than what I was used to. Rather than using return values from a stub method for the response, JAXWS has this idea of using the javax.xml.ws.Holder class for return values. Kinda odd, but... whatever. Maybe there is a way to change the client-side programming model, but I wasn't going to worry about that right then.

There is some stuff in the Exchange interface (WSDL) having to do with impersonation and SerializedSecurityContext in each request on the EWS Service port, which is not useful. I'm using neither of those things, yet they are included in every Web services stub method. Passing null for these parameters does not satisfy, I get an error saying that I cannot set that to xsi:nil unless the schema has nillable='true'. I tried fiddling with the WSDL.. to set it to nillable in the right spots... That didn't work, so I just removed that stuff from the WSDL completely, from every wsdl:message in the WSDL file:

        <wsdl:message name="GetFolderSoapIn">
                <wsdl:part name="request" element="tns:GetFolder" />
<!-- dinoch - change for JAXWS
                <wsdl:part name="Impersonation" element="t:ExchangeImpersonation"/>
                <wsdl:part name="S2SAuth" element="t:SerializedSecurityContext"/>
                <wsdl:part name="MailboxCulture" element="t:MailboxCulture"/>
-->
                <wsdl:part name="RequestVersion" element="t:RequestServerVersion"/>
        </wsdl:message>

and also from every soap:operation:

                <wsdl:operation name="GetItem">
                        <soap:operation soapAction="http://schemas.microsoft.com/exchange/services/2006/messages/GetItem" />
                        <wsdl:input>
<!--
                                <soap:header message="tns:GetItemSoapIn" part="Impersonation" use="literal"/>
                                <soap:header message="tns:GetItemSoapIn" part="S2SAuth" use="literal"/>
                                <soap:header message="tns:GetItemSoapIn" part="MailboxCulture" use="literal"/>
-->
                                <soap:header message="tns:GetItemSoapIn" part="RequestVersion" use="literal"/>
                                <soap:body parts="request" use="literal" />
                        </wsdl:input>
                        <wsdl:output>
                                <soap:body parts="GetItemResult" use="literal" />
                                <soap:header message="tns:GetItemSoapOut" part="ServerVersion" use="literal"/>
                        </wsdl:output>
                </wsdl:operation>
                <wsdl:operation name="CreateItem">

Ok, I was getting somewhere. With this change I was able to send a FindItem message over the wire to Exchange, and get message IDs back. Very cool. The approach I was taking was to use findItem to get the item IDs, and then use GetItem on the Ids to get the full content. The FindItem() was working flawlessly, but the GetItem() was not. I was not getting the results I expected. No exceptions, but my data was not coming back.

To troubleshoot this, I used Fiddler2 to see the HTTP messages back and forth between Java and Exchange. Because the communication was using SSL for encryption, Fiddler2 does not work. Some people have used Charles, a similar web debugging proxy. But I already had Fiddler, so... With the fiddler tool I could see exactly why the GetItem message was not giving me joy. (By the way, if you use Fiddler to decrypt SSL traffic, it's necessary to specify to the Java app that it should accept any SSL traffic - basically disable cert validation in the application. Only do this for testing purposes!!)

Correct flow from a .NET app to Exchange:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
      <ItemShape>
        <BaseShape xmlns="http://schemas.microsoft.com/exchange/services/2006/types">Default</BaseShape>
        <AdditionalProperties xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
          <FieldURI FieldURI="item:Subject" />
          <FieldURI FieldURI="item:Body" />
          <FieldURI FieldURI="item:Categories" />
          <ExtendedFieldURI PropertySetId="0006200E-0000-0000-C000-000000000046" PropertyId="35584" PropertyType="Integer" />
          <ExtendedFieldURI PropertyTag="0x10F3" PropertyType="String" />
          <ExtendedFieldURI PropertyTag="0x3008" PropertyType="SystemTime" />
        </AdditionalProperties>
      </ItemShape>
      <ItemIds>
        <ItemId Id="AAAZAERpbm8uQ2hpZXNhQG1pY3Jvc29mdC5jb20ARgAAAAAALBHixAbt0hGt6gCAX5/eGgcAd75VstDi0RGt3QCAX5/eGgAAAnopngAAEKx2OMNuVUuHEMvofVOxpwANFT4iewAA" ChangeKey="AAAAABQAAAAdMskaJAAzTpK1s6mN4vCnAAhyCw==" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" />

Broken flow from a JAXWS app to Exchange:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
    <ns2:RequestServerVersion xmlns="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:ns2="http://schemas.microsoft.com/exchange/services/2006/types" Version="Exchange2007_SP1" />
  </S:Header>
  <S:Body>
    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:ns2="http://schemas.microsoft.com/exchange/services/2006/types">
      <ItemShape>
        <ns2:BaseShape>Default</ns2:BaseShape>
        <ns2:AdditionalProperties>
          <ns2:Path xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:PathToUnindexedFieldType" FieldURI="item:Subject" />
          <ns2:Path xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:PathToUnindexedFieldType" FieldURI="item:Body" />
          <ns2:Path xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:PathToUnindexedFieldType" FieldURI="item:Categories" />
        </ns2:AdditionalProperties>
      </ItemShape>
      <ItemIds>
        <ns2:ItemId ChangeKey="AAAAABQAAAAdMskaJAAzTpK1s6mN4vCnAAhyCw==" Id="AAMkAGUwNmJhYWVjLTI1ZTgtMTFkMy05MDc5LTAwODA1ZjMxZjgyNgBGAAAAAAAsEeLEBu3SEa3qAIBfn94aBwB3vlWy0OLREa3dAIBfn94aAAACeimeAAAQrHY4w25VS4cQy+h9U7GnAA0VPiJ7AAA=" />

Exchange wasn't sending me the data I expected, because the JAXWS request message was not what Exchange expected it to be. With this understanding, I looked into the contract. For the element in question, the schema used a ref="type" structure, and this was the only use of the ref in the entire contract. Clearly causing a problem; JAXWS was formatting it strangely. I modified it to eliminate the ref, just as a test.

  <!-- Arrays of paths -->
  <xs:complexType name="NonEmptyArrayOfPathsToElementType">
    <!-- using choice here so that proxy generator will not flatten the array and thus lose the
                item element names -->
    <xs:choice maxOccurs ="unbounded">
<!-- dinoch - change for jaxws -->
  <xs:element name="Path" type="t:BasePathToElementType"/>
  <xs:element name="FieldURI" type="t:PathToUnindexedFieldType" />
  <xs:element name="IndexedFieldURI" type="t:PathToIndexedFieldType" />
  <xs:element name="ExtendedFieldURI" type="t:PathToExtendedFieldType"/>

<!--
      <xs:element ref="t:Path"/>
-->

    </xs:choice>
  </xs:complexType>

After re-generating the client-side stubs, I was able to get the GetItem message to work nicely. Here's the message from JAXWS after the change in schema:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
    <ns2:RequestServerVersion xmlns="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:ns2="http://schemas.microsoft.com/exchange/services/2006/types" Version="Exchange2007_SP1" />
  </S:Header>
  <S:Body>
    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:ns2="http://schemas.microsoft.com/exchange/services/2006/types">
      <ItemShape>
        <ns2:BaseShape>Default</ns2:BaseShape>
        <ns2:AdditionalProperties>
          <ns2:FieldURI FieldURI="item:Subject" />
          <ns2:FieldURI FieldURI="item:Body" />
          <ns2:FieldURI FieldURI="item:Categories" />
        </ns2:AdditionalProperties>
      </ItemShape>
      <ItemIds>

After that, it was a matter of writing up the code to use the jaxws-generated stubs. It all works nicely now. It's pretty darn fast, too!

Let me summarize what I did to get Java to talk to Exchange:

Modified the exchange.wsdl to include a service definition, and to remove all occurrences of impersonation, S2SAuth, and MailboxCulture from each wsdl:message.
Modified the types.xsd to eliminate the ref="t:Path", and replace it with actual elements
Use Fiddler2 to trace and debug the SOAP messages.

The bottom line is that web services interop is possible even with complicated schema and interfaces, if you are willing to get your hands dirty on the schema, and if you choose the right tools.

In part 2 of this story, I'll show you some of the application code that uses the JAXWS-generated client classes, and I'll pack up the source code for everything too.

Great resources:

Cheers,
-Dino

Connecting Java to Exchange over WebDAV, with Apache HttpClient

DotNetInterop — Mon, 21 Jul 2008 19:47:00 GMT

Earlier I mentioned a Java Exchange Connector I had seen, and in that post I also said that I had some code that connected from Java to Exchange Server via WebDAV. Some people have asked for the code, so here it is.

I use a set of Apache libraries to make this possible: Apache Commons HttpClient for the Java SSL client capability, and Apache Jakarta Slide for the WebDAV piece. As you may have heard, Slide was discontinued as a project a while ago. So maybe you are thinking, Slide? What good is that code if it depends on an abandoned Apache library?. A reasonable point. Honestly though, the Slide stuff is really not that critical for this scenario. Basically, WebDAV is a standard for formatting queries that get sent over HTTP. But in my case, I am just cons-ing up strings that contain the queries. It would be pretty easy to factor out the WebDAV/Slide stuff, I think. I didn't bother to do it, only because I wrote the code a long time ago, well before Slide was discontinued, and I didn't really feel like investing the time to re-factor it now.

The httpclient and slide jars also drag in the commons-logging and codec jars from Apache.

I have the full working proof-of-concept code attached to this post as a zipfile. It is a JSP-based app that runs in Tomcat or Jetty or your favorite servlet container. Requires JDK 1.5 to build it. You can have a look and try it out yourself. Here's the code I use to send out a query to Exchange.

  public org.w3c.dom.Document search(String urlString, String request, int depth, String range) 
    throws Exception
  {
    Document doc= null;

    SearchMethod method = new SearchMethod(urlString, request); 
    try {
      //method.setRequestHeader("Content-type", "text/xml");
      method.setRequestHeader("depth", ""+depth) ;
      method.setRequestHeader("Translate", "f");

      // must set Content-Length explicitly.  Why doesn't the SearchMethod do this?  Who knows. . .
      method.setRequestHeader("Content-Length", String.valueOf(request.length()));

      if ((range!=null) && (range !=""))
          method.setRequestHeader("Range", range);

      int rc = httpclient.executeMethod(method);

      doc = method.getResponseDocument();
    }

    finally {
      // release any connection resources used by the method
      method.releaseConnection();
    }            

    return doc;
  }

Ok, that's just some boilerplate WebDAV stuff. Get a request, set the HTTP headers, send out the request. The magic really is in the request itself. This is what a WebDAV request looks like on the wire:

SEARCH /exchange/dinoch/Inbox HTTP/1.1 
depth: 1 
Translate: f 
Content-Length: 370
Range: rows =0-3
Content-Type: text/xml; charset=utf-8
User-Agent: Jakarta Commons-HttpClient/3.1
Host: mail.microsoft.com
Cookie: $Version=0; sessionid=40e73022-93d3-4739-99ff-bf60fd60fcee; $Path =/
Cookie: $Version=0; cadata=1 gGfmglWDAmcLGmstqx3kSpuecb1BVBmjFwiD0IIem2hm6IsfCLr7DSo63ncgdM7xNi3E5A==; $Path= /

<searchrequest xmlns='DAV:' >
  <sql> 
    SELECT "DAV:id", "DAV:href" , "urn:schemas:httpmail:subject", "urn:schemas: httpmail:from", "urn:schemas:httpmail:datereceived" 
    FROM SCOPE('shallow traversal of "https://mail.microsoft.com/exchange/dinoch/Inbox"') 
    WHERE "DAV:ishidden"=False AND "DAV:isfolder"=False 
  </sql>
</searchrequest>

In that request, I'm searching on my Exchange Inbox. I can also search on any folder: Calendar, Contacts, Notes, Tasks, any mail folder, and so on. The schema are different for different item types, so ya gotta be careful there. Anyway, in the above request, I search on the first 4 rows, and I ask for the fields: subject, id, href, from, and datereceived.

In the proof of concept, I create these queries using a file-based template, one for each type of query. I have a template for the inbox query, another template for the query of the tasks folder, and so on. This is the template for the Tasks query, for example:

<searchrequest  xmlns='DAV:'>
  <sql>
    SELECT 
       "DAV:href", 
       "DAV:displayname", 
       "DAV:getlastmodified",
       "urn:schemas:httpmail:subject",
       "urn:schemas:httpmail:textdescription",
       "http://schemas.microsoft.com/mapi/id/{00062008-0000-0000-C000-000000000046}/0x00008517" as DueDate2,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x8101" AS Status,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x8102" AS PercentComplete,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x8104" AS StartDate,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x8105" AS DueDate,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x810f" AS DateCompleted,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x811c" AS IsComplete,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x8113" AS State,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x8110" AS ActualEffort,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x8111" AS EstimatedEffort,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x8518" AS Mode,
       "http://schemas.microsoft.com/mapi/id/{00062003-0000-0000-C000-000000000046}/0x811f" AS Owner

    FROM SCOPE('shallow traversal of  "##FOLDERPATH##"')
    WHERE "DAV:ishidden"=False AND "DAV:isfolder"=False  
    ORDER BY IsComplete, DueDate ASC 

 </sql>
</searchrequest>

One of the trickiest areas for me was just figuring out the MAPI schema for all the various fields that might be present in a given document type (like task, message, meeting request, contact, note, and so on) that can be stored by Exchange. The schema are not intuitive, nor did I find the documentation to be easily accessible. As you can see, there are some magic incantations above for the task document type.

Just so everyone is clear: The schema used is the same, regardless of the type of client. I am writing a Java app here. But you could use these same queries from a .NET app, a VBScript app, or a PHP app, or Ruby or whatever. The Exchange Server responds to the on-the-wire protocol, and doesn't care about the client you use.

Another key part is logging into the Exchange server. This is the method I use to login.

  public void login (String destUrl, String username, String password) 
    throws Exception
  {
    Username= username;

    String[] urlParts=destUrl.split("/");
    String server= urlParts[2]; 
    String authDllPath= "/exchweb/bin/auth/owaauth.dll";
    String AuthUrl= Protocol + "://" + server + authDllPath;

    //System.setProperty("javax.net.debug", "all");  // too much information
    //System.setProperty("javax.net.debug", "ssl");

    // the class ionic.ssl.SSLSocketFactoryImpl must be available for the classloader,
    // eg, on \lib\ext
    java.security.Security.setProperty("ssl.SocketFactory.provider",
                                       "ionic.ssl.SSLSocketFactoryImpl");

    if (!server.equals(Servername)) 
      throw new Exception ("Cross-site redirection attempt.");

    PostMethod method = new PostMethod(AuthUrl);

    try {

      //System.out.println("DavConnection: Logging in with u/p: " + username + " | " + password); 

      method.setFollowRedirects(false); // false == default

      NameValuePair[] data = {
        new NameValuePair("destination", destUrl),
        new NameValuePair("username", username),
        new NameValuePair("password", password)
      };
      method.setRequestBody(data);

      int rc = httpclient.executeMethod(method);
      int stat= method.getStatusLine().getStatusCode(); 
        
      if (stat== 302) {  // 302 = Moved Temporarily (this is success)

        // The response form Exch2003 says "Moved Temporarily" but 
        // if we are only logging in, we don't need to follow this link. 
        // The apache commons httpclient runtime will log an INFO
        // saying "302 received but followRedirects==false.  This is OK. 

        // String redirectLocation= null; 
        // Header locationHeader = method.getResponseHeader("location");
        // if (locationHeader != null) 
        // redirectLocation = locationHeader.getValue();
        // System.out.println("Redirect to: " + redirectLocation);

      }
      else 
        throw new Exception("Unexpected HTTP status code during login (" + stat +")");
    } 
    finally {
      // release any connection resources used by the method
      method.releaseConnection();
    }            
  }

This login method is exposed on a DavConnection object, the class/type that wraps all the interaction with Exchange server. After login, of course, I set the DavConnection into the http session. It gets returned as a cookie to the browser. Thereafter when the browser connects and presents its cookie, we have te active Exchange connection. We only login once.

At this point I want to talk about cookies. My favorite kind are oatmeal cookies, which I love to make. When I make 'em, I tend to eat them, all of them. So I don't make 'em that often. My second-favorite kind of cookies are HTTP Cookies. There are two sets of HTTP cookies in this application scenario. One set of cookies links the browser to the JSP app. Another set of cookies links the JSP app to Exchange Server.

The second set, the cookies that Exchange sends back to the client that is authenticating (in this case our JSP app) must be retained and presented back to the server on subsequent queries. Nicely for us, the Apache HttpClient library does that automagically for us. The DavConnection class embeds an HttpClient instance as a member; this HttpClient instance retains the cookies that keep the conversation with Exchange alive. mmm-kay?

Let's see what else? I guess you will want to have a look at a sample response from an Exchange WebDAV query. This is one response I got.

<a:multistatus xmlns:b="urn:uuid:c2f41010-65b3-11d1-a29f-00aa00c14882/" xmlns:d="urn:schemas:httpmail:" xmlns:c="xml:" xmlns:a="DAV:">
  <a:contentrange>0-9</a:contentrange>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/RE:%20Developing%20and%20debugging%20without%20admin%20rights.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47Tx0AAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/RE:%20Developing%20and%20debugging%20without%20admin%20rights.EML</a:href>
        <d:subject>RE: Developing and debugging without admin rights</d:subject>
        <d:from>"Alun Jones" &lt;alunj@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T21:26:24.409Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/MarieHu%20team%20meeting:%20FY06%20plans%20%26%20budget.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxGAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/MarieHu%20team%20meeting:%20FY06%20plans%20%26%20budget.EML</a:href>
        <d:subject>MarieHu team meeting: FY06 plans &amp; budget</d:subject>
        <d:from>"Marie Huwe" &lt;mariehu@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T21:23:44.107Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/Repeater%20control%20%3CItemTemplate%3E%20question.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxMAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/Repeater%20control%20%3CItemTemplate%3E%20question.EML</a:href>
        <d:subject>Repeater control &lt;ItemTemplate&gt; question</d:subject>
        <d:from>"Mike Burdick" &lt;mikebu@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T21:23:06.000Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/Work%20on%20the%20update%20to%20the%20Business%20Section%20of%20the%20RTB%20Slide%20Deck.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxZAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/Work%20on%20the%20update%20to%20the%20Business%20Section%20of%20the%20RTB%20Slide%20Deck.EML</a:href>
        <d:subject>Work on the update to the Business Section of the RTB Slide Deck</d:subject>
        <d:from>"Paul Barcoe-Walsh" &lt;paulbwa@exchange.microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T20:52:48.000Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/RE:%20demo%20script%20updates%20-%2060min:%20403%20on%20notify%20ws.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxSAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/RE:%20demo%20script%20updates%20-%2060min:%20403%20on%20notify%20ws.EML</a:href>
        <d:subject>RE: demo script updates - 60min: 403 on notify ws</d:subject>
        <d:from>"Jonathan Moons" &lt;jmoons@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T20:46:05.000Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/ACTION:%20New%20launch%20BOM%20in%20effect.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxQAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/ACTION:%20New%20launch%20BOM%20in%20effect.EML</a:href>
        <d:subject>ACTION: New launch BOM in effect</d:subject>
        <d:from>"Bill Dunlap" &lt;bdunlap@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T20:43:09.000Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/You%20available%20to%20talk%20today_x003F_.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxRAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/You%20available%20to%20talk%20today_x003F_.EML</a:href>
        <d:subject>You available to talk today?</d:subject>
        <d:from>"Terry Leeper" &lt;tleeper@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T20:07:57.694Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/MarieHu%20team%20meeting:%20Overview%20of%20the%20Connected%20Systems%20Generico%20application.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxYAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/MarieHu%20team%20meeting:%20Overview%20of%20the%20Connected%20Systems%20Generico%20application.EML</a:href>
        <d:subject>MarieHu team meeting: Overview of the Connected Systems Generico application</d:subject>
        <d:from>"Marie Huwe" &lt;mariehu@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T20:02:45.693Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/Blowfish%20implementations%20for%20.NET.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxKAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/Blowfish%20implementations%20for%20.NET.EML</a:href>
        <d:subject>Blowfish implementations for .NET</d:subject>
        <d:from>"Kevin Hammond" &lt;kevinha@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T19:48:00.000Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
  <a:response>
    <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/Out%20of%20Office%20AutoReply:%20SF%20and%20Interop.EML</a:href>
    <a:propstat>
      <a:status>HTTP/1.1 200 OK</a:status>
      <a:prop>
        <a:id>ARkAAAACUCbqAQAAQL47TxBAAAAA</a:id>
        <a:href>https://mail.microsoft.com/Exchange/dinoch/Inbox/Out%20of%20Office%20AutoReply:%20SF%20and%20Interop.EML</a:href>
        <d:subject>Out of Office AutoReply: SF and Interop</d:subject>
        <d:from>"Mike Wons" &lt;mikewons@microsoft.com&gt;</d:from>
        <d:datereceived b:dt="dateTime.tz">2005-04-11T19:35:23.673Z</d:datereceived>
      </a:prop>
    </a:propstat>
  </a:response>
</a:multistatus>

Just standard XML. I use an XSL sheet to transform that into some readable HTML. In the interest of completeness, here it is:

<xsl:stylesheet 
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    version="1.0"
    xmlns:a="DAV:"
    xmlns:m="urn:schemas:httpmail:" 
    xmlns:c="urn:schemas:contacts:" 
    xmlns:java="java" 
  >

<!-- Contacts.xsl                                                         -->
<!--                                                                      -->
<!-- This sheet is used to Transform XML obtained from an Exchange        -->
<!-- webdav query into html.                                              -->
<!--                                                                      -->
<!-- Tue, 12 Apr 2005  15:11                                              -->


<xsl:param name="PageNumber"/>
<xsl:param name="UserName"/>
<xsl:param name="FolderName"/>
<xsl:param name="PageName"/>
<xsl:param name="CurrentTimeFormatted"/>


<xsl:output 
    method="html" 
    indent="yes" />

  <xsl:template match="a:multistatus">
    <xsl:variable name="FolderDecoded"
              select="java:net.URLDecoder.decode($FolderName, 'UTF-8')" >
    </xsl:variable>
    <xsl:choose>
      <xsl:when test="number($PageNumber) > 1">
      <a>
          <xsl:attribute name="href"><xsl:value-of select="$PageName"/>?action=itemizeFolder&amp;ref=<xsl:value-of select="$FolderName"/>&amp;page=<xsl:value-of select="number($PageNumber)-1" /></xsl:attribute>
            &lt;&lt;prev</a>
      </xsl:when>
      <xsl:otherwise>
      &#160; &#160; &#160; &#160; &#160;
      </xsl:otherwise>
    </xsl:choose>

    &#160;
    <a>
          <xsl:attribute name="href"><xsl:value-of select="$PageName"/>?action=itemizeFolder&amp;ref=<xsl:value-of select="$FolderName"/>&amp;page=<xsl:value-of select="number($PageNumber)+1" /></xsl:attribute>
           next&gt;&gt;
    </a>
    
    <h2>Folder:<xsl:value-of select="$FolderDecoded"/></h2>
    <h3>User: <xsl:value-of select="$UserName"/><br/>
    as of: <xsl:value-of select="$CurrentTimeFormatted"/></h3>
    <table border='1'> 
    <xsl:apply-templates select="*" />
    </table> 
  </xsl:template>

  <xsl:template match="a:contentrange" />

  <xsl:template match="a:response">

    <tr>
     <xsl:choose>

      <!-- ============================================================ -->
      <xsl:when test="$FolderName = 'Inbox' or $FolderName = 'Sent Items' or $FolderName = 'Deleted Items'  or $FolderName = 'Junk E-mail'  " >
      <td>
        <a>
            <xsl:attribute name="href"><xsl:value-of select="$PageName"/>?action=get&amp;item=<xsl:value-of select="a:href" /></xsl:attribute>
              <xsl:value-of select="a:propstat/a:prop/m:subject" />
        </a> 
        </td>
        <td style="font-size:8pt;">
              <xsl:value-of select="translate(a:propstat/a:prop/m:from, '\\', '')" />
        </td>
        <td>
           <xsl:value-of select="substring(a:propstat/a:prop/m:datereceived,0,11)" />&#160;<xsl:value-of select="substring(a:propstat/a:prop/m:datereceived,12,8)" />
        </td>

      </xsl:when>

      <!-- ============================================================ -->
      <xsl:when test="$FolderName = 'Contacts'">
        <td>
        <a>
            <xsl:attribute name="href"><xsl:value-of select="$PageName"/>?action=get&amp;item=<xsl:value-of select="a:href" /></xsl:attribute>
             <b> <xsl:value-of select="a:propstat/a:prop/c:fileas" /></b>
        </a> 
        </td>
        <td style="font-size:8pt;">
              <xsl:value-of select="a:propstat/a:prop/c:telephoneNumber" />
        </td>
      </xsl:when>

      <!-- ============================================================ -->
      <xsl:otherwise>
      <!-- xsl:when test="$FolderName = 'Notes'"  -->
        <xsl:variable name="ItemName"> 
        <xsl:choose>
          <xsl:when test="substring(a:propstat/a:prop/a:displayname,string-length(a:propstat/a:prop/a:displayname)-3) = '.EML'">
            <xsl:value-of select="substring-before(a:propstat/a:prop/a:displayname,'.EML')" />
          </xsl:when>
          <xsl:otherwise>
            <xsl:value-of select="a:propstat/a:prop/a:displayname" />
          </xsl:otherwise>
        </xsl:choose>
        </xsl:variable>

        <td>
        <a>
            <xsl:attribute name="href"><xsl:value-of select="$PageName"/>?action=get&amp;item=<xsl:value-of select="a:href" /></xsl:attribute>
             <b> <xsl:value-of select="$ItemName" /></b>
        </a> 
        </td>
        <td style="font-size:8pt;">
              <xsl:value-of select="a:propstat/a:prop/a:getlastmodified" />
        </td>
      </xsl:otherwise>
     </xsl:choose>
    </tr>
  </xsl:template>
</xsl:stylesheet>

Of course, in the more general case, you're not going to just be displaying the result you got from querying exchange. Instead you will be extracting data and mashing it up with something else. In that case you will want to do XPath or DOM walky stuff on the XML doc. And you know how to do that, right?

All the code is available attached here. I hope you all find it useful!

Just a quick disclaimer before I go: I Really DO NOT recomend that people constructing new apps use WebDAV to connect to Exchange Server. Exchange Server 2007 supports a standards-compliant Web services interface, which is much easier to use than the WebDAV interface. If you have a choice, please consider using the web services option.

Cheers!
-Dino

Java Exchange Connector and EWSJ

DotNetInterop — Tue, 17 Jun 2008 17:19:00 GMT

Just saw this on TheServerSide.com. The Exchange Web Services for Java (EWSJ - what happened to the 4?). It's a Java class library that ~~uses the Apache AXIS web services stack to connect~~ connects to Microsoft Exchange Server 2007, via the published and supported Exchange Web Services interfaces.

What you can do with this is connect to Exchange 2007 from any Java app. A good example is when building an HR or group scheduling app, in Java. (While I love .NET, not everyone has seen the light! and some poor developers are relegated to using Java even for new applications.) In the scenario where you write in Java and the enterprise messaging standard is Exchange, the EWSJ library may come in handy.

There's a beta of the Exchange Web Services for Java out now; it looks like the company updates the beta fairly regularly. They mention a free academic license, so I guess they will be licensing EWSJ for a fee for other purposes.

The company also has something called the JEC, which I guess is the Java Exchange Connector. I don't understand the difference between EWSJ and JEC. Based on reading, I'm guessing they do the same thing - provide access for Java apps into the Exchange store - but I think the JEC is based on the older WebDAV interface into Exchange, and EWSJ uses the web services interfaces. ~~Just a guess... I don't know. Maybe someone can enlighten me.~~ Confirmed: JEC uses WebDav and EWSJ uses EWS.

This EWSJ works with the Web services interfaces supported by Exchange 2007. By the way, those are the same web services interfaces I use from a Windows Forms app running in .NET, and the same interfaces I use from a Windows Mobile app running on my smartphone.

It brings up an interesting question - why pay for EWSJ - or any third-party library that wraps web services interfaces - when the webservices interfaces are public and free-of-charge? I mean, if you have the WSDL and XML Schema, and you have access to good Web services tooling (Apache AXIS for Java, WCF in .NET), then you could just build (generate) the client-side proxies and classes and get connected, right? But, there's an opportunity to add in value to the interface - like caching of content, caching of credentials, simplifying the interface, integrating with other frameworks, and so on. The approach I took with my .NET work was to use the tools and published interfaces. But I can see value in depending on a third party library that adds some additional capability. I don't know much about EWSJ, so I don't know what's been added, but I see the opportunity for the company to deliver something interesting there.

By the way, I have also previously demonstrated the use of WebDAV interfaces to get to Exchange Server from Java, prior to version 2007, as the JEC does it. You can get from a JSP to Exchange 2003 for example, using WebDAV. The way I did it was, like the JEC approach, to depend on the Apache libraries. In my case, just as with the JEC, I used the now-retired Jakarta Slide library and the httpclient from the commons package. I can publish this source code if you like. (But if you are running Exchange 2003, you really should upgrade. E2007 is much much better, and the web services interface is just one aspect.)

I was surprised to see that Jakarta Slide has been retired! Apparently it didn't attract enough developers. But it looks like there is a new WebDAV implementation in the Apache Jackrabbit project. I guess this is a challenge facing all open-source projects. With so much attention focused on AJAX and pretty web interfaces, internetworking protocols like WebDAV take a back seat. Good to see WebDAV is not totally dead at Apache.

EWSJ looks like one more interesting interop opportunity.