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.
Here's the technology background for this work:
|Email Server:||Exchange 2007 SP1 (with Exchange Web Services enabled)|
|Programming Language:||Java 1.5 or later|
|Application Server:||Oracle Application Server 10g (production)|
|Glassfish v2 (local development)|
|Web Service Stack:||Glassfish Metro (guide for deployment on OC4J later)|
|Development IDE:||NetBeans 6.1 (guide for Eclipse 3.4 later)|
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.
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.
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:
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.
Web Service Client can not be created by JAXWS:wsimport utility. Reason: Could not find wsdl:service in the provide WSDL(s): ... You need to provide at least one WSDL with at least one service definition.
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:
Web Service Client can not be created by JAXWS:wsimport utility. Reason: Undefined Attribute 'xml:lang' There might be a problem during java artifacts creation: for example a name conflict in generated classes.
The offending line is around line 3370 of types.xsd. It reads:
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.
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:
wsimport-client-generate: Created dir: /home/[your username]/ExchangeWebServices/build/web/WEB-INF/classes wsimport-client-compile: Compiling 409 source files to /home/[your username]/ExchangeWebServices/build/web/WEB-INF/classes BUILD SUCCESSFUL (total time: 19 seconds)
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:
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.
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.
I've updated this article a few times as I receive user comments and look into questions further: