Recently I was given the opportunity to write an online email client at my job. Throughout the application, at key points of contact, we will integrate message creation for students to seamlessly contact instructors, advisors, classmates, fellow club members, etc. Also, we wanted a full email client worked into the application. My point is, there are good reasons for writing the email client. This is not just some pipe dream.

Technology Background

Here's the technology background for this work:

Enable Exchange Web Services

The first step in this process, is to speak with your Exchange administrator. Have him or her turn on Exchange Web Services. If they're turned on, you should be able to get the WSDL at https://mail.example.com/EWS/exchange.asmx (which redirects to https://mail.example.com/ews/Services.wsdl in most cases, I believe). Remember this URL for later.

Set up your development environment

You will need two core pieces of technology to get started developing. The first is an application server. Download Glassfish v2 (or Glassfish v3 if you're savvy). You will also need a development environment. Install NetBeans 6.1. If you're using Linux, check your package manager first. The files may be available through your distribution. If you're on Ubuntu Linux, like I am, install the netbeans and glassfishv2 packages. If you're on Windows, Mac, or feel like doing a manual Linux install, use the links above and the corresponding installation directions.

Preparing NetBeans

We will need a few NetBeans plugins: Java EE, Web Applications, Web Services, and Glassfish. Install them through the plugin manager at Tools → Plugins. Also, do any recommended plugin/platform updates at this time as well.

Now we have to add Glassfishv2 as a server in NetBeans:

1. Go to Tools → Servers → Add Server...
2. In the 'Choose Server' dialog box that comes up, select Glassfishv2 as your server and click 'Next'.
3. In the next screen, set 'Platform Location' to the directory where you installed Glassfish.
   • Note: On Ubuntu, if you installed from the repositories, this is /usr/share/glassfishv2
4. Also, select 'Register Local Default Domain'. The default domain for most installs is ${glassfish_home}/domains.
   • I ran into several issues on Ubuntu setting 'Register Local Domain'. The following instructions are for Ubuntu users only:
     1. The pre-configured default domain from the package manager is et up at /var/lib/glassfishv2/domains/domain1 but if you try to enter this as the 'Domain Folder' you will get the error Cannot find valid domain.xml file. I believe this is because the platform location and domain folder are in two different locations.
     2. So I had to stop the default domain executing sudo /var/lib/glassfishv2/domains/domain1/bin/stopserv.
     3. Then, back in NetBeans at the 'Platform Folder Location' dialog, I selected 'Create Personal Domain' with the default profile.
     4. Go out to the operating system's file manager and create the folder /home/[your username]/glassfishv2/domains
     5. Back in NetBeans on the 'Domain Folder Location' dialog. Set the 'Domain Folder' to /home/[your username]/glassfishv2/domains/netbeans_domain and click next.
     6. Set your desired administrator username and password and click next.
     7. On the 'Creation Properties' dialog I noticed I was not suggested the standard ports for my application server. So if you want to use the standard port numbers (recommended) make sure they're all set to the following values:
        • Admin Port: 4848
        • Admin JMX Port: 8686
        • Domain HTTP Port: 8080
        • JMS Port: 7676
        • ORB Listener Port: 3700
        • HTTPS Port: 8181
        • ORB SSL Port: 3820
        • ORB MultiAuth Port: 3920
     8. Click 'Finish'
5. After finishing you should now see the server startup messages show up in the NetBeans console. It will end in Domain netbeans_domain created.

Setting up the NetBeans Project

Create a new project of type Web → Web Application. I set mine up as a JavaEE 5 project. After the project has been created you'll see a generic NetBeans web project.

Remember that WSDL file from earlier? We're finally ready to start using it. Unfortunately, Microsoft didn't format it 100% correct. There's some discussion on the topic over at the MSDN forums. The WSDL being provided by Exchange is missing a wsdl:service element. If you tried to add a Web Service Client pointing at this WSDL you'd get the error.

To get around this error, download the file at https://mail.example.com/ews/Services.wsdl and save a copy locally in your project's web folder, eg. [NetBeans Project Folder]/web/exchange.wsdl. If you tried to create a Web Service Client from this WSDL you'll see that the relative references to messages.xsd and types.xsd are broken. So you also need to download copies of https://mail.example.com/ews/messages.xsd and https://mail.example.com/ews/types.xsd and save them in the same local folder as the WSDL.

So now that we have all the files necessary, let's edit that WSDL to be valid. Open it up in NetBeans from your 'Web Pages' folder. At the second to last line, before the final tag place the following XML code:

Microsoft's provided XML is still not ready for parsing. If you tried to read the file now, you'd get the error:

The offending line is around line 3370 of types.xsd. It reads <xs:attribute ref="xml:lang" use="optional"></xs:attribute>. Someone please tell me how to get around this error if you have a better solution. For the time being I just commented the line out like <!-- <xs:attribute ref="xml:lang" use="optional"></xs:attribute> -->.

Generating the Java code

Finally! We're done fixing up the WSDL's and XSD files that Microsoft has presented. Let's generate some code. In NetBeans, right click on the project and select New → Web Service Client.

In the dialogs that come up:
Local File: [NetBeans Project Folder]/web/exchange.wsdl
Client Style: JAX-WSl

Click 'Finish' and you'll start the generation of your web services client from the WSDL file. You should see a bunch of build script output and compiling going on below in the NetBeans output area. If it's successful, it will end with something like:

Now, to develop code using these web services, the NetBeans documentation recommends using their "Web Service Client Resources → Call Web Service Operation" context menus and code generation. I find this terribly annoying and would rather just copy the generated Java files into the src folder of my project:

1. Open up your operating system's file manager.
2. Browse to [NetBeans Project Folder]/build/generated/wsimport/client
3. You'll see one folder in here named 'com'. This is the start of the com.microsoft.schemas.exchange.services._2006 packages. So copy the 'com' folder.
4. Navigate back to [NetBeans Project Folder]/src/java and paste the 'com' folder in here.

Now open up NetBeans again and you should see all the 409 generated Exchange Web Service files in your source package split into two package groups. Congratulations! The toughest part of this entire tutorial series is over.

Conclusion

The frustrations I went through figuring all this out is 50% of what inspired this tutorial series you're reading now :) I felt there were no good Java/Exchange Web Service guides out there, esp. tailored to Metro/NetBeans. In my next article, I will go over authenticating through web services and returning a successfully authenticated ExchangeServicePortType.

Note: Please, if you have suggested improvements to this article, or any other comments I encourage you to leave me feedback. I'd love to get some constructive criticism, or hear back if the guide helped you.

Revisions

I've updated this article a few times as I receive user comments and look into questions further:

• Jan 15, 2009: Updated the "Generating the Java code" section, and included a link to the NetBeans documentation for how they recommend invoking web service operations, and how I think their way is annoying.