Providing a .NET control that facilitates this as Open Source is definitely on the to-do list for the Exchange Web Services project, but I was not sure how I would do this for OpenEdge as non-UI controls are not supported and most of the work that the control does is communication with the Exchange Web Service in a multi-threaded configuration on background threads. 

On May 5th, Progress temporarily raised the restriction to test the OpenEdge GUI for .NET bridge with controls that have no user-interface so that users can experiment with the controls and determine what types of controls should be supported. My company, Intangere, thus signed up for the program and created a control that mimics the behavior of a proposed Exchange Web Services control. This test has been surprisingly successful, and this article provides some information about the test and the code and a document that describes its use.

Architecture

Progress would have had logistical issues incorporating an Exchange Web Server into their nightly build simply to test the background functionality that this control will provide. To test the functionality, therefore, I needed to provide Progress with an example that replicates the functionality that I expect to use in the Exchange Web Services architecture.

The model at left graphically demonstrates how the architecture of the code works. The model closely mimics the model for the Subscription and Notification API that  I discussed in the Exchange Web Services – Subscriptions and Notifications post that I wrote back on April 26th.

Starting from the right of the diagram, Listener.exe is intended to emulate the functions that are performed by the Microsoft Exchange Web Services API. Specifically, it supports registering subscriptions and notifying the client of "updates" on a background thread. All communication between the client and Listener.exe is by means of .NET objects serialized as XML. 

The EWSEmulator Control is a .NET control that has no user interface and performs the function that the Java EWS WebService and the Java HTTP Servlet perform. As such, it is derived from System.ComponentModel.Component and it handles the job of communicating with Listener.exe, both in terms of posting subscription requests, and in terms of receiving notifications. The control receives the notifications on a background thread (the Notification Processor) which deserializes the objects and hands them to the event generator which raises a .NET event on the UI thread.

Receiving the event on the UI thread is one of the most critical components of this control. OpenEdge is single-threaded which means that if an event is raised on anything but the UI thread, it is likely to cause problems for OpenEdge. So the Event Generator's sole function is to marshal all notifications and generate a .NET event on the UI thread.

The User Interface Logic is responsible for registering subscriptions via the embedded EWSEmulator Control, shutting down the Listener service and reacting to events raised by the Event Generator.

So how did the test go?

I'm not going to spend a lot of time telling you about the gory details of the code. You can download the code and a document that describes a lot more about my experience and findings, and you can even run it and look at both the ABL and .NET code. The document is a PDF contained in the zip file. 

In a nutshell, though, I was able to duplicate the behavior I was looking for, marshal the events onto the UI thread, and get OpenEdge to react to those events without too much trouble. Section 4.2.2 of the document provides a description of how the marshaling works.

More importantly, I was also able to establish that the volume of data that can be handled by the OpenEdge ABL in this kind of communication was significantly greater than I had thought. I was able to generate upwards of 400 messages per second from Listener.exe and the client handled them without losing any.

Of course, no one in their right mind would expect the client to handle that volume of traffic, especially considering that every event had to be marshaled to the UI thread. But it was encouraging to learn that it was possible.

My Conclusion

What this test has proven is that the OpenEdge GUI for .NET is more than capable of supporting background controls, provided they conform to the rule that all threads need to be marshaled to the UI thread before an event is raised.

Also, I made extensive use of the XmlSerializer, HttpListener, HttpWebResponse, and several other streaming classes and had no problem at all with OpenEdge. 

I have submitted this code and these findings to Progress Software and hopefully they will be able to lift the restriction on use of non-UI controls with OpenEdge GUI for .NET.

Feel free to download the example code and documentation and mess with it, and please let me have your feedback.

Also note that the program with Progress to test the bridge for non-UI controls is open until July 31st, so if you can join the program and contribute, please do. 

Goals and Background

Part 2 of this series of articles is dedicated to giving you an overview of the process of connecting to Exchange and doing some basic Calendar item work. Through the sample code, you will learn how to:

1. Connect to the Exchange Web Service from Java;
2. Create calendar items on the Exchange Server;
3. Get calendar items from the Exchange Server;
4. Delete calendar items from the Exchange Server; and
5. Connect to the Java service from OpenEdge to perform the same operations.

The Java functionality will be exposed as a Web Service for other platforms to leverage, which is how we will get at it from OpenEdge. The OpenEdge code leverages the new GUI for .NET and object-oriented extensions, so you may find the example interesting if you are an OpenEdge developer who has not done this before.

One of the things that I have learned about integration through bitter, painful experience, is that it is much easier if you remove as many variables as possible, so, for the purposes of this exercise, I am only going to expose a few of the calendar properties. This helps to keep the code simple and this article reasonably short. I think I succeeded at the former, but the latter… not so much.

The code that you will be looking at is code that I wrote as part of my research into the EWS API and, as such, it is prototype code. What this means is that it is ugly. I have not spent a lot of time commenting it and it does not resemble the code that I would deploy to production from an object-model point of view. But that is OK. A prototype is intended to prove a concept.

There is nowhere that integration is harder than when you try and integrate Microsoft's technologies with a non-Microsoft platform. Microsoft seems to make it deliberately difficult. I have therefore deliberately hand-coded the SOAP messages that are used to communicate with Exchange in this example. I started out by trying to use Java frameworks like Axis 2 and JAX-WS for the SOAP piece, but I quickly ran into problems. So I decided that I would remove those variables and prove I could get the code working. Now that I am satisfied that I can do what I need to be able to do, I will go back and decide what I am going to do about integrating one of these frameworks into the mix. 

Another important factor that I should point out about this prototype is that I plan to integrate this whole solution with an Enterprise Service Bus (specifically, Apache ServiceMix). So it is really important to me that this can function as a properly service-oriented solution – hence the focus on web service enablement. Ultimately the service will generate messages that can be captured and interrogated in the service bus using a complex event processing engine.

Setting up the Code

Assuming you followed my instructions in part 1and now have the environment working, you can download the code for this article. The zip file contains two projects:

• EWSAPI – This is an Eclipse Java EE  project that is intended to be deployed to a Glassfish server. It contains the Java code that does the actual communication with Exchange and accepts WebService requests from external sources.
• OEEWS – This is an Eclipse project that is intended to be deployed in an OpenEdge Architect workspace that calls the Java WebService.

Both of these projects can be imported in the same way as I described in part 1, under the heading "Running a quick test to prove it works", although you should be aware that EWSAPI should be imported into a Java EE workspace, whereas OEEWS should be imported into an OpenEdge Architect workspace. I have had problems trying to run OE Architect in the same workspace as a Java EE configuration, so I don't recommend you try it.

After you have imported EWSAPI into your Java EE workspace, go ahead and drag it across to the Glassfish server in the server view and it will be deployed for you, ready to run.

The OEEWS project does not require any special configuration. Just import it into OpenEdge Architect and you will be good to go. Note that this code was written and compiled under 10.2B01 so I don't know how compatible it is with earlier versions.

Turn on line numbers

In the remainder of this series of articles, I will be cross-referencing the code that I have provided in the zip file. When I do so, I will mention specific line numbers that map to the line numbers in the source file. It will help you a lot if you turn the line number feature on for all editors in Eclipse so that you can follow along.

Also note that I occasionally include portions of the source code in the article for easy reference, but when I do, I do not include the line numbers so the line number reference refers to the example code.

To turn line numbers on, follow these steps:

1. From the Window menu, choose "Preferences"
2. Expand the "General->Editors" nodes and select "Text Editors"
3. Make sure the "Show line numbers" check box is checked as in the screenshot at left.

Understanding Code Contents

As mentioned, the code for this first article is divided into a Java EE project and an OpenEdge project. The two projects will grow over this series of articles. Here's a brief description of these two projects and how they relate to the rough architecture that I am working on.

EWSAPI – Exchange Web Services API

The EWSAPI project is a Java Web Service that accepts Web Service requests to a defined API, turns around and passes them on to Microsoft Exchange. 

In the diagram at left, therefore, the EWSAPI project contains the code that is the endpoint for the arrow numbered 1.1, and the source for the arrow numbered 1.2.

An important part of a SOA architecture is a canonical data model that can be used to abstract the integration from the implementation, and for me, this service will later act as the separation point between the business layer and the Microsoft Exchange communication. As I work through this in more detail, it is becoming apparent that what I am currently thinking of as the EWSAPI will ultimately be split into two completely separate components. I think there is a good case to be made for an abstraction API that allows you to plug in other adapters to work for other calendar and e-mail servers.

The source code for this article in the EWSAPI project contains three WebService operations:

• CreateAppointment
• GetAppointment
• DeleteAppointment

Something to be aware of is that the APIs that we are going to be working with can do substantially more than I am going to talk about in this article. For example, an appointment can have an invitee list, recurrence, attachments, and so on. I am more focused on showing you how to create the appointment on the Exchange Server, retrieve the appointment from Exchange, and delete it. I may come back to the more detailed stuff in later posts.

As an aside, I wrote most of this code before I decided on the structure of these articles. My test environment is already set up to support things like Exchange Impersonation and Subscriptions. As a result, some of the code that I am providing you here already supports some of that functionality, but some of it is only half-implemented, so don't go onto those things until we get to those articles because the code may not work properly. 

OEEWS – OpenEdge Exchange Web Services API

The second project is the OEEWS project which contains the OpenEdge ABL code that allows you to call each of these APIs from OpenEdge. I have created a .NET style UI in OpenEdge that allows you to connect to the service, generate 10 appointments automatically and randomly, fetch an appointment from the server, view it, and delete it.

Yes, I know my UI is ugly, but it's a prototype so who cares. If you don't like it, fix it.

The OEEWS component corresponds with the trigger point for the 1.1 arrow in the diagram above, so this article is purely about communicating with Exchange. We are not worried about the subscription API (all the #2 arrows) just yet. 

Another thing to know about the OEEWS code is that I have liberally mixed procedural, object-oriented and .NET UI code in together. My primary audience for the OpenEdge code is people who have never worked with the OO stuff before, so I want them to get comfortable with it and realize that it is not that complicated.

Now that you know what is in the mix, let's get down to the code and understand what is going on. If you are an OpenEdge ABL developer, this first section is going to look a little scary – it's Enterprise Java. You may not recognize the code, but I am pretty sure you will understand it once I have walked through it, so hang on tight. You won't want to skip down to the ABL section because there are concepts that I am going to talk about that you need to understand in the following section.

The EWS API

The Java-based EWSAPI consists of 5 source code files in 3 packages. The files are:

• EWSCalendar.java – Contains the source code file for the web service itself and it lives in the org.tsg.ews package;
• Appointment.java – Contains a class that represents a Calendar item, including properties for the appointment and methods to create, get, and delete appointments. It lives in the org.tsg.ews.calendar package;
• EWSResponse.java – Contains the source code for a class that acts as a container for the response that is returned from Exchange. It lives in the org.tsg.ews.service package;
• ExchangeService.java – Contains a class that abstracts the connection to an Exchange Web Service. It lives in org.tsg.ews.service package; and
• SOAPRequest.java – Contains a class that is responsible for actually calling the Exchange Web Service.

Go ahead and open Eclipse for Java EE, and, assuming you have already imported the EWSAPI project into your workspace, expand the EWSAPI node. Underneath that, expand the "Java Resources: src" node and expand each of the packages. Then go ahead and open EWSCalendar.java so that your UI looks like this:

Now let's dig into this code. 

EWSCalendar

The EWSCalendar class is the main entry point in the the Java code on the server. The class exposes a Web Service that consists of 3 methods:

• createAppointment;
• getAppointment; and
• deleteAppointment.

Each of these methods does pretty much what its name implies. The code in EWSCalendar actually does very little work. It is the facade that exposes the service for use as a Web Service. 

Web Services Annotations

Setting up a Web Service in Java EE is as simple as annotating a class for use as a Web Service. In line 15, there is an attribute that annotates the following class, EWSCalendar, as a Web Service with a name "AppointmentService". 

Lines 18 and 19 contain annotations that specify that createAppointment should be treated as a Web Service operation called "CreateAppointment" and that the node in the SOAP document that is returned from the call should have a node called "Response" that contains the output parameter for the call. In line 20, createAppointment is defined as returning an EWSResponse object, and the remainder of line 20 through line 30 define the parameters for the createAppointment call. Each parameter is annotated with a WebParam annotation that provides the name of the XML node that must be created for its value.

Lines 45 through 51 do the same thing for the GetAppointment operation and lines 58 through 64 do the same thing for DeleteAppointment. That's all that is required to define a Web Service. I don't need to generate a WSDL or anything. Java EE does that all for me automatically based on the annotations for the methods.

Now if you are a Java programmer looking at the parameters for this call, you may be wondering why the parameters are not defined as objects. The simple answer is because it is a lot easier to work with this call in OpenEdge if each parameter is specifically defined, than it is to expect an appointment object, say, as an input parameter for CreateAppointment.

CreateAppointment

Going back to to line 31, the code for CreateAppointment looks like this:

ExchangeService srvc = new ExchangeService(hostName, domain, username, passwd);
Appointment appt = new Appointment(srvc);
appt.setDescription(description);
appt.setLocation(location);
appt.setStartDate(startDate);
appt.setEndDate(endDate);
appt.setNotes(notes);
appt.setReminder(reminder);
appt.setReminderMinutes(minutes);
EWSResponse resp = appt.create();
return resp;

In line 32, I create an ExchangeService object, using the host name for the Exchange CAS Server that hosts the Exchange Web Service API, the domain name of the user for whom an appointment is being created, and the user name and password for that user. We'll dive into what this code actually does in a few minutes, but for the moment let's finish off the createAppointment call.

Line 33 instantiates an Appointment object using the ExchangeService object created in the line before and lines 33 through 39 set a number of properties of that appointment. Description is actually the subject of the appointment and lines 38 and 39 set the reminder for the appointment. 

Line 40 calls the create method on the appointment and this is the code that does all the work. The create method returns an EWSResponse object, which is annotated for JAXB XML serialization to produce the XML results that we need.

The Appointment Object and JAXB XML Serialization

Now I'd like you to open Appointment.java in the org.tsg.ews.calendar package. You can skip down to lines 22 and 23, because there is something here that affects getAppointment later. You'll note in these two lines that there are two more annotations:

@XmlRootElement(name = "Appointment")
@XmlAccessorType(XmlAccessType.PROPERTY)
public class Appointment {

The two @Xml annotations are for JAXB which will automatically serialize the whole Appointment class into a root element called "Appointment." The second annotation tells JAXB to look at all get… and set… methods as properties and turn them into XML. If you scroll down to line 70, you'll see an annotation "@XmlElement(name = "Subject") just before the getDescription method that tells JAXB to serialize this property into an XML element (not an attribute) called "Subject". So the value of this property will be serialized as follows:

<Subject>Go catch some flies - 01</Subject>

Again, XML serialization for classes is built in to Java EE. This piece of things is important for you to understand, because the same mechanism has been applied to EWSResponse so that its data can be serialized into the SOAP message that will be the return value to the CreateAppointment call.

The Create Method

Now scroll down to the create() method in Appointment.java in line 278:

public EWSResponse create() {
	DatatypeFactory dtf = DatatypeFactory.newInstance();
	StringBuffer request = new StringBuffer();
	request.append("<CreateItem \n");
	request.append("               SendMeetingInvitations=\"SendToNone\"\n");
	request.append(String.format("               xmlns=\"%1$s\"\n", SOAPRequest.MESSAGES_URI));
	request.append(String.format("               xmlns:t=\"%1$s\">\n", SOAPRequest.TYPES_URI));
	request.append("    <Items>\n");
	request.append("        <t:CalendarItem>\n");
	request.append("            <t:Subject>");
	request.append(description);
	request.append("</t:Subject>\n");
	if (notes != null) {
		request.append("            <t:Body BodyType=\"Text\">");
		request.append(notes);
		request.append("</t:Body>\n");
	}
	if (reminder) {
		request.append("            <t:ReminderIsSet>true</t:ReminderIsSet>");
		request.append("            <t:ReminderMinutesBeforeStart>");
		request.append(Integer.toString(reminderMinutes));
		request.append("</t:ReminderMinutesBeforeStart>\n");
	}
	if (startDate != null) {
		request.append("            <t:Start>");
		request.append(dtf.newXMLGregorianCalendar(startDate).toXMLFormat());
		request.append("</t:Start>\n");
	}
	if (endDate != null) {
		request.append("            <t:End>");
		request.append(dtf.newXMLGregorianCalendar(endDate).toXMLFormat());
		request.append("</t:End>\n");
	}
	if (location != null) {
		request.append("            <t:Location>");
		request.append(location);
		request.append("</t:Location>\n");
	}
	request.append("        </t:CalendarItem>\n");
	request.append("    </Items>\n");
	request.append("</CreateItem>\n");

Lines 280 through 319 simply build up the body of the SOAP message that needs to be sent to Exchange for it to create the appointment.

One of the things about Exchange Web Services that is critical to understand is that there can be no mistake in this XML. It needs to appear exactly as it is defined in the Exchange SDK, otherwise it will not work. The order of the elements is absolutely critical. I have spent a lot of time trying to figure out why a call was not working, only to find that the the XML was badly formatted or a node was spelled incorrectly. Exchange does not help you here. You simply get a 500 – Internal Server Error message from the Web Server which is about as much use as an udder on a bull.  

In line 282, we start out by defining a CreateItem node that contains an Items node that has one CalendarItem node in it. Namespacing is very important, so lines 284 and 285 set up the appropriate namespaces from constants defined in the SOAPRequest class.

Lines 288 through 290 serialize the subject while lines 291 through 295 handle the Notes or Body of the appointment. Lines 296 through 301 handle the reminder and lines 302 through 311 handle the start and end dates for the appointment. After handling the location in lines 312 through 316, we end off by closing out the XML tags.

The rest of the code in this method looks like this:

SOAPRequest req = new SOAPRequest(request.toString(), emailAddress);
EWSResponse retVal = service.makeRequest(req);
lastResponse = retVal;
id = retVal.getId();
changeKey = retVal.getChangeKey();
return retVal;

Now it's important to realize that all we have created is the part of the SOAP message that tells Exchange what we want it to do – create a calendar item. We haven't wrapped it in a SOAP message yet. Line 321 takes care of doing this by creating a SOAPRequest object based on the request string that we just created. Ignore the fact that we pass in an emailAddress at this point, because that will be used later for the Exchange Impersonation article.

If you want to go and explore the SOAPRequest class, feel free to do so. It simply creates the SOAP envelope and plugs the request information that we passed in into the body of the SOAP message. No rocket science in this.

The next step (line 322) is to call the makeRequest() method on the ExchangeService object that was passed in when we created the appointment.  We'll dig into this call in a minute, but let's just finish out understanding what the rest of this method is doing. 

The makeRequest() method call returns us an EWSResponse object that we can return to the caller. Before we do that, though, we set two very important pieces of information inside this Appointment object.

Items and Item IDs

When any item (e-mail, contact, task, or appointment) is created on an Exchange Server, it is allocated two pieces of information:

1. An Item ID. This is universally unique inside Exchange. No two items will ever have the same Item ID, even across different mailboxes, and this becomes the mechanism that we need to refer to the item later;
2. A ChangeKey. This piece of information is almost like a SHA1 or MD5 checksum that tells what the state was of the item at the point that you created it. This becomes very important later when we update these items.

You'll note that I have switched from referring to the things we are creating as Calendar items to simply calling them Items. That's because in Exchange, everything that can be created inside a folder (something we'll deal with later) is considered an Item. E-mail, Contacts, Tasks and Appointments are all items. This is another important concept to get clear, because if you look back at line 282, you'll note that the node that we created was a CreateItem node and that it contained a CalendarItem node inside an Items node.

Lines 324 and 325 set the values of the Item ID and ChangeKey for this appointment respectively. I also store the EWSResponse object in the Appointment in case it is needed later. I don't have code that uses this right now, though. Line 326 returns the EWSResponse object to the caller and lines 328 through 330 catch any exceptions and turn them into an EWSResponse object that can be serialized.

ExchangeService

The next thing to do is to take a look at the code in the ExchangeService class in the org,tsg.ews.service package. The guts of the communication with Exchange happens in the makeRequest method, which begins at line 57. You'll note that the first thing that makeRequest does is call "setAuthenticator" in line 58. The code in setAuthenticator is critical to our communication with Exchange, so scroll down to line 91 and we will pick up there.

setAuthenticator

The following is the code that is contained in setAuthenticator:

private void setAuthenticator() {
	System.setProperty("http.auth.preference", BASIC_AUTHENTICATION);
    	System.setProperty("http.auth.digest.validateServer", "false");
    	System.setProperty("http.auth.digest.validateProxy", "false");

	Authenticator.setDefault(new Authenticator() {
		@Override
		protected PasswordAuthentication getPasswordAuthentication() {
			StringBuffer user = new StringBuffer(domain);
			user.append("\\");
			user.append(username);
			System.out.println("Authentication...");
	   		System.out.print("Requesting Prompt: ");
			System.out.println(this.getRequestingPrompt());
	    		System.out.print("Requesting Scheme: ");
			System.out.println(this.getRequestingScheme());
	   		System.out.print("Requestor Type: ");
			System.out.println(this.getRequestorType());

			return new PasswordAuthentication(user.toString(), password.toCharArray());
		}

	});
}

This code has gone through a number of iterations and there are a lot of debug messages that I have put in here to try and figure out what I could do about the authentication piece of things. As I mentioned in part 1, this code currently only works with basic authentication switched on. The first System.setProperty call sets the authentication mode to basic authentication. The next two properties only apply with digest authentication and you can ignore them. 

The Authenticator.setDefault() call sets a default authenticator class that takes the user name and password that were supplied earlier, and makes them available for authentication purposes when the Exchange Web Service requests credentials.

The big problem with this code is that it sets these credentials for the entire JVM. This is a bad thing, especially in the Java EE environment, but there are solutions that I have already found to fix this problem that I will blog about later. For now, the purposes of what I am currently trying to achieve, this is good enough, and an important thing to remember is that I am looking at this as server-side code so Exchange Impersonation is a key component of the strategy going forward. In the impersonation model, the problem is not as serious as it is right now.

The reason this is such a serious risk right now is that you need to shut down and restart the Glassfish AppServer between changing the user for whom the appointment is being created. But I figured that as this is the only article that will use this model, we're OK with that limitation.

Making the call

Now we need to go back to line 60 in the makeRequest function:

URL ewsURL = new URL(String.format(EWS_URL, this.hostName));  // Substitute the host name into the URL.);
HttpsURLConnection ewsConn = (HttpsURLConnection) ewsURL.openConnection();
ewsConn.setRequestMethod("POST");
ewsConn.setRequestProperty("Content-type", "text/xml;utf-8");
ewsConn.setDoInput(true);
ewsConn.setDoOutput(true);

Line 60 sets up a URL for the Exchange Server. The String.format call substitutes the hostName provided into the EWS_URL constant so that the Exchange Web Service API is called. The constant is defined in line 25.

Update: Since I wrote this article, I have installed and tested Microsoft Exchange Server 2007 SP3 and Microsoft Exchange Server 2010. There is one minor modification you will need to make to the sourced code that accompanies this article for it to work with these. Line 63 of the source code file "ExchangeService.java" that accompanies this article reads:

ewsConn.setRequestProperty("Content-type", "text/xml;utf-8");

It may need to be changed to read:

ewsConn.setRequestProperty("Content-type", "text/xml;charset=utf-8");

Next we set up an https connection, set the request method to post, and several other properties of the connection. Line 67 contains a debug message that displays the entire XML for the SOAP message just prior to posting the call to the Exchange Web Server and lines 69 through 72 actually post the message to the Exchange Server:

PrintWriter pout = new PrintWriter(new OutputStreamWriter(ewsConn.getOutputStream(), "UTF-8"), true);
pout.print(message.getMessage());
pout.flush();
pout.close();

Receiving the response

All calls to Exchange are followed by a response:

EWSResponse resp;
if (ewsConn.getResponseCode() == HttpsURLConnection.HTTP_OK) {
        BufferedReader bin = new BufferedReader(new InputStreamReader(ewsConn.getInputStream()));

        StringBuilder result = new StringBuilder();
        String line;
        while( (line = bin.readLine()) != null )
        	result.append(line);
        System.out.println(result.toString());
        resp = new EWSResponse(result.toString());

In line 75, we check to see that the response we got from the Web Service was an OK – 200. If it is, line 76 instantiates a BufferReader to read the URL connection's input stream. Lines 78 through 81 read the contents of that stream into a string which we display in line 82 so we can see the response we got from Exchange.

Line 83 then takes that response and instantiates an EWSResponse object with the string we got back, and the EWSResponse object parses the SOAP message that we received from Exchange and stores the response in object. Among the things that is returned is a ChangeKey, an ID and the error status of the call. I'm not going to spend much time talking about EWSResponse here, other than to say that it parses the XML using the standard DOM in the JVM.

The remainder of the makeRequest() method deals with what happens if we don't get an OK http response:

} else {
	System.out.println (String.format("Error code: %1$s - %2$s", ewsConn.getResponseCode(), ewsConn.getResponseMessage()));
	resp = new EWSResponse("HTTPError", ewsConn.getResponseCode(), ewsConn.getResponseMessage());
}
return resp;

Line 85 provides the details of the response as a debug message and line 86 creates an EWSResponse object that provides details of the error. The most likely scenarios for this response are 401 errors (HTTP authentication failed) or 500 errors (the XML was not properly understood by Exchange and it reports an "Internal Server Error"). The 500 errors are a pain because there is no information available on why you got them. You have to guess, and it is this that made me hand-code the XML that is being sent to the Exchange Server.

Now that we have an EWSResponse object, it can be returned to the caller, serialized and returned from the WebService to whatever the source was.

Testing it out with soapUI

The next step is to try and test this. Make sure you have your Glassfish server running and that the EWSAPI code is deployed to the server. You can check this by switching to the Servers view in Eclipse for Java EE and looking at the status of the GlassFish V3 Java EE 6 server. Start the server if necessary and drag the whole EWSAPI node to the GlassFish server node and it will be deployed for you.

The next step is to start soapUI and create a new project. Right-click on the Projects node and create a new project. You should see the following dialog:

The URL that need to type in the "Initial WSDL/WADL" field is:

http://localhost:8080/EWSAPI/AppointmentService?wsdl

Once you have entered that URL, make sure the check boxes are as they appear in the screenshot above, and choose the OK button. SoapUI will generate a project for AppointmentService and it will have three operations under it. Go ahead and expand the tree so that all the nodes are visible. The three operations are CreateAppointment, GetAppointment, and DeleteAppointment. Each of them has a "Request 1" node under it. I have renamed those nodes to "CreateApptRequest", etc, so that when a request is open, I can differentiate it from the others.

Before we execute a call, open Outlook for the account that you are testing against so you can see what happens in Outlook when the appointment is created.

Double-click on the CreateAppointment request in soapUI and open the XML editor will open with the XML Soap message in the left-hand pane. Remember, there is no validation, so make sure you type all the right values between the tags in the XML document.

The first parameter for the call is the Exchange Server. You need to type the fully qualified domain name of the Exchange Web Services host that you are trying to call. Next is the domain. This is the domain that is used for the Windows login. Username and password are fairly self-explanatory, as are the Description, Location and Notes elements. 

SetReminder should be either "true" or "false". If "true", a reminder will be set for the appointment that will go off a certain number of minutes before the appointment. ReminderMinutes is an integer that specifies how many minutes lead-time the reminder should have.

StartDateTime and EndDateTime are exactly what they say they are, but they are ISO dates that include a time zone. The date is in yyyy-mm-dd order and is followed by a T to indicate that the rest of the field is all time. The time is a 24 hour time format, including a 3 digit decimal for the number of milliseconds. So 5:00pm is 17:00:00.000. The last section of the time is an offset from Universal Standard Time(UTC). I'm on the West Coast of the US, so in the Northern Hemisphere Summer, we are 7 hours behind UTC. Thus my timezone information is -07:00. If I were in South Africa, I'd be two hours ahead of UTC which would be +02:00.

Once you have all these fields filled out, you can execute the call. In the right-hand pane of the request, you should get a SOAP message back that tells you what happened. If all went well, there will be a single response node that contains three attributes – ChangeKey, ItemID and ErrorStatus. The ErrorStatus should be "NoError" and the other two attributes will have very long strings in them that mean nothing, but I've already explained what these are. 

If you get this, your appointment has been created in Exchange and if you have Outlook open in the background, a second or two later the appointment will show up in the calendar as you can see in the screenshot above.

If you are having trouble getting any kind of response back, go to Eclipse for Java EE, and switch to the Glassfish Server log in the Console view as follows:

You will need to select the down-arrow next to the console button in the toolbar in the Console view. Select the log file from the two console sources, and it will show the messages that were output as the code was running.

Now that we have successfully created the appointment, you need to keep the result of the call around, because you are going to need it in a few minutes when we run the GetAppointment call.

For the moment, though, let's switch back to the Eclipse for Java EE and look at the code for GetAppointment and DeleteAppointment.

GetAppointment

If we switch back to the EWSCalendar class, lines 45 through 56 contain the code for retrieving an appointment from Exchange:

@WebMethod(operationName = "GetAppointment")
@WebResult(name = "Appointment")
public Appointment getAppointment(@WebParam(name = "ExchangeServer") String hostName,
				@WebParam(name = "Domain") String domain,
				@WebParam(name = "User") String username,
				@WebParam(name = "Password") String passwd,
				@WebParam(name = "AppointmentID") String id) {
	ExchangeService srvc = new ExchangeService(hostName, domain, username, passwd);
	Appointment appt = new Appointment(srvc);
	appt.retrieve(id);
	return appt;
}

As I mentioned earlier, the first couple of lines are annotations needed for exposing this call as a Web Service called GetAppointment. Note that this method returns an object of type Appointment, the class we learned about earlier on. All this call does is instantiate an ExchangeService object, instantiate an Appointment object, retrieve it, and return it. The Java EE WebServices framework takes care of serializing the Appointment object to XML.

The retrieve() method takes an Item ID as a parameter so that it retrieves the calendar item by means of that Item ID.

Appointment.retrieve()

The retrieve() method in line 157 of the Appointment class is responsible for crafting the XML message that gets sent to the Exchange Server:

public EWSResponse retrieve(String itemID) {
	try {
		StringBuffer request = new StringBuffer();
	        request.append("<GetItem \n");
	        request.append(String.format("               xmlns=\"%1$s\"\n", SOAPRequest.MESSAGES_URI));
	        request.append(String.format("               xmlns:t=\"%1$s\">\n", SOAPRequest.TYPES_URI));
	        request.append("    <ItemShape>\n");
	        request.append("          <t:BaseShape>Default</t:BaseShape>\n");
	        request.append("          <t:AdditionalProperties>\n");
	        request.append("              <t:FieldURI FieldURI=\"item:Body\"/>\n");
	        request.append("              <t:FieldURI FieldURI=\"item:ReminderIsSet\"/>\n");
	        request.append("              <t:FieldURI FieldURI=\"item:ReminderMinutesBeforeStart\"/>\n");
	        request.append("          </t:AdditionalProperties>\n");
	        request.append("    </ItemShape>\n");
	        request.append("    <ItemIds>\n");
	        request.append(String.format("        <t:ItemId Id=\"%1$s\"/>\n",itemID));
	        request.append("    </ItemIds>\n");
	        request.append("</GetItem>\n");
		SOAPRequest req = new SOAPRequest(request.toString(), emailAddress);
		EWSResponse retVal = service.makeRequest(req);
		if ((!retVal.hasError()) && retVal.getElement() != null) {
			parseItem(retVal.getElement());
		}
		lastResponse = retVal;
		return retVal;
	}
	catch (Exception e) {
		return new EWSResponse(e);
	}
}

The first thing to note about this code is that there is nothing in it that indicates that the object that we are retrieving is a Calender Item. As far as Exchange is concerned, we are retrieving an item, and it does not care what type of item it is. So the call we make is a GetItem call.

Lines 163 through 170 define an ItemShape object. The ItemShape tells Exchange what we are interested in retrieving about this item. The BaseShape node tells it to retrieve the most basic properties of the item, but we need additional data like the Body (or notes), the Reminder flag and the number of minutes in advance that the reminder is required. So the AdditionalProperties node asks Exchange to retrieve these properties, too.

Lines 171 through 173 tell Exchange what item IDs to return – in our case there is always only one.

In line 175 we create the SOAP envelope for the call and in line 176 we call makeRequest to retrieve the data from Exchange. Assuming all went well with the call, we set the values of all the fields in the Appointment by calling parseItem() in line 178. I'm not going to spend a lot of time explaining the XML parsing. Just take it from me that the code parses the XML node for the appointment and gets the right values out.

Of course, if the call failed, we need the client to know that, so we store the EWSResponse object in the appointment. The advantage of that is that the EWSResponse object is XML-serializable so it will be serialized with the Appointment object. Another nice thing about JAXB is that it will ignore null elements (unless you tell it not to). What this means is that if the Appointment object's properties are null, they will not be written to the XML response.

That's pretty much it. Now let's see what happens when we run it.

Testing GetAppointment with soapUI

Before you switch back to soapUI, go to the appointment that we created earlier, and make some changes to it in Outlook. Add some stuff in the notes and change the date and time or something. Now switch back to soapUI and highlight and copy (Ctrl+C) the Item ID that is in the Response node in the right side pane of the CreateApptRequest window we opened earlier. 

Now open the GetAppointment request and set all the values for the credentials as you did earlier:

The Appointment ID node needs to contain the Item ID that you copied from the CreateApptRequest above. Once you have pasted that in and executed the call, you should get a response that contains all the information about the appointment that we requested. Note that the changes that you made are retrieved with the call. I should mention that sometimes you have to wait a few seconds for Exchange to commit your changes and notify the Client Access Server before your changes become available for retrieval by Exchange Web Services.

DeleteAppointment

Last, but not least is DeleteAppointment. The code for this is actually very simple. If we go back to Eclipse for Java EE and look at EWSCalendar again, lines 58 through 67 contain the code that does the work:

@WebMethod(operationName = "DeleteAppointment")
@WebResult(name = "Response")
public EWSResponse deleteAppointment(@WebParam(name = "ExchangeServer") String hostName,
				@WebParam(name = "Domain") String domain,
				@WebParam(name = "User") String username,
				@WebParam(name = "Password") String passwd,
				@WebParam(name = "AppointmentID") String id) {
	ExchangeService srvc = new ExchangeService(hostName, domain, username, passwd);
	EWSResponse resp = Appointment.delete(srvc, id, null);
	return resp;
}

By now, hopefully you understand everything down to line 66. In line 66, we call Appointment.delete() and pass in the service and an Item ID. When the call is complete, we simply return the EWSResponse object that should give us error status.

Appointment.delete()

The guts of the work happens in the Appointment object, so switch to that editor and go to line 26:

public static EWSResponse delete(ExchangeService srvc, String itemID, String emailAddress) {
	try {
		StringBuffer request = new StringBuffer();
	        request.append("<DeleteItem \n");
	        request.append(String.format("               xmlns=\"%1$s\"\n", SOAPRequest.MESSAGES_URI));
	        request.append(String.format("               xmlns:t=\"%1$s\"\n", SOAPRequest.TYPES_URI));
	        request.append("           DeleteType=\"MoveToDeletedItems\"\n");
	        request.append("           SendMeetingCancellations=\"SendToNone\">\n");
	        request.append("    <ItemIds>\n");
	        request.append(String.format("        <t:ItemId Id=\"%1$s\"/>\n",itemID));
	        request.append("    </ItemIds>\n");
	        request.append("</DeleteItem>\n");
		SOAPRequest req = new SOAPRequest(request.toString(), emailAddress);
		EWSResponse retVal = srvc.makeRequest(req);
		return retVal;
	}
	catch (Exception e) {
		return new EWSResponse(e);
	}
}

Again, hopefully this code looks very similar to the GetItem call we did earlier. The DeleteItem node has two interesting attributes in lines 32 and 33. You'll see the DeleteType attribute which tells Exchange to move the deleted appointment to the Deleted Items folder. You can specify exactly what to do with the item, including a hard delete – permanent deletion.

In line 33, the SendMeetingCancellations attribute tells Exchange what to do about notifying people about the cancellation of the appointment.

Line 34 through 36 contains the list of Item IDs to be deleted (in our case, just one). Lines 38 through 40 create the SOAP envelope, make the call to Exchange and obtain and return the EWSResponse object. That's all there is to it.

Testing DeleteAppointment with soapUI

The last step in the Java tests is to see if the DeleteAppointment API works. Make sure you have the Item ID for the appointment you created earlier, and open the DeleteAppointment request. As with the GetAppointment API, paste the Item ID into the Appointment ID node:

If all goes well, the response will be contained in a Response node and the ErrorStatus will be NoError. If you switch to Outlook, the appointment has been removed and if you switch to the Deleted Items folder, you will see the Calendar Item in that folder.

Java Summary

That's all there is to the Java side of things for this article. You have now learned how to use Java to create, get and delete calendar items using the Exchange Web Services API. The next article will focus on Exchange Impersonation.

If you're a Java developer, and you have no interest in the OpenEdge component, thank you for your attention. I hope this was useful to you.

If you are an OpenEdge developer, don't go anywhere – we're going to see how to call this Web Service from inside OpenEdge. 

The OE EWS Components

If you have been following the code up until now, you have a running instance of Glassfish and it's ready for you to test the OpenEdge code that calls these three Web Service operations. Go ahead and open OpenEdge Architect and make sure you have imported the OEEWS project into OpenEdge Architect.

Once you have imported it, expand the src folder all the way down until your Resources are expanded as in the screenshot below:

Just so there is no confusion, my screenshots were taken of the code as I have it checked into my Subversion repository, so you can ignore the date, time and user name next to each source code element. That is information that Subversion adds.

The first code that we are going to look at is in the CreateAppointments.p procedure as this code creates a batch of 10 appointments, so go ahead and open this procedure in OE Architect.

CreateAppointments.p

There really is no rocket science about this code. For the most part, it is ordinary OpenEdge ABL/4GL code. Lines 14 and 15 of the source file do contain two statements that are specific to object-oriented ABL:

USING Progress.Lang.*.
USING com.tsg.ews.*.

These two lines tell the compiler that my code references objects in the Progress.Lang package and in the com.tsg.ews package. Don't fret about this just yet.

Line 20 references a temp-table definition that is in an include file while lines 21 through 24 define 3 input parameters and an output parameter table for the temp-table defined in the include file.

The rest of the code down to line 39 is pretty standard 4GL, but in line 39, I define a variable called "appt" that is of type com.tsg.ews.Appointment. If you cast your eyes across to the Resources view, you will see a file called Appointment.cls under the src/com/tsg/ews folder. Appointment.cls contains an OpenEdge class definition, and we will look at this code a little later. The Using statement in line 15 told Progress to look in the com/tsg/ews folder for any classes that I refer to.

The interesting code starts in line 43 (I have removed comments below for brevity):

REPEAT iCount = 1 TO 10:

    appt = new Appointment().
    appt:Subject = pcDescription + " - " + STRING(iCount, "99").
    appt:Location = pcLocation.
    appt:Notes = pcNotes.
    appt:StartDateTime = figureOutStartDate(dWorkDate).
    appt:EndDateTime = DATETIME-TZ(DATE(appt:StartDateTime), MTIME(appt:StartDateTime) + iDuration, TIMEZONE ).
    dWorkDate = appt:EndDateTime.

    appt:SaveAppointment().        

    CREATE ttAppointment.
    IF appt:ItemID <> ? AND
       appt:ItemID <> "" THEN
       cString = appt:ItemID.
    ELSE
       cString = STRING(iCount).  

    ASSIGN
        ttAppointment.description = appt:Subject
        ttAppointment.startdate = DATETIME(DATE(appt:StartDateTime), MTIME(appt:StartDateTime)).
        ttAppointment.enddate = DATETIME(DATE(appt:EndDateTime), MTIME(appt:EndDateTime)).
        ttAppointment.itemid = cString.
    .

END.

This repeat loop occurs 10 times. In line 46, I create a new instance of an Appointment object and I assign the reference to the appt variable. What this means is that I have an empty Appointment object. In lines 21- 23 I defined 3 input parameters for the appointment description, location and notes. In 47, 48 and 49, I set the Appointment's corresponding properties from these input parameters.

In line 50, I set the start date and time for the appointment to the return value of the figureOutStartDate function. I'm not going to walk through the code for the function here, but I'll tell you that it goes and calculates a date on a work day (Monday through Friday) between 9 and 5, skipping an hour for lunch at 12:00pm. It also sets a variable that is global to this procedure called iDuration. This contains the length of the appointment in milliseconds. In line 51, I set the end date and time to the start date and time plus the duration.

The upshot is that I will get 10 appointments that follow each other of random duration and with random gaps between them starting from now, until all 10 appointments are scheduled.

Line 57 calls SaveAppointment and this method on the Appointment object is responsible for calling the Web Service. We'll get to this code in a minute or two. When the appointment is successfully saved, we set the ItemID property of the Appointment object to the return value from Exchange.

Lines 60 through 72 create a temp-table record for this appointment and store the subject, start date, end date and item id. This is just regular 4GL code. 

Appointment.cls

Next, we'll take a look at the code in Appointment.cls. Go ahead an open it in the editor.

Appointment.cls is an OpenEdge ABL class that uses OpenEdge Object-Orientation. Lines 16 through 20 declare the class and define some variables. Lines 22 through 24 define the default constructor for the Appointment object. This is the code that is called when an object is instantiated as it was in line 46 of CreateAppointment.p. Line 26 through 30 declares a constructor that we will use later for GetAppointment. 

Lines 32 through 68 declare several properties for the Appointment object that we used to set the appointment values in lines 47 through 51 of CreateAppointments.p above.

Skip on down to line 87, and we will take a look at the code that actually saves the appointment:

METHOD PUBLIC LOGICAL SaveAppointment():
    DEFINE VARIABLE srvc AS EWSService NO-UNDO.
    DEFINE VARIABLE hHandle AS HANDLE NO-UNDO.
    DEFINE VARIABLE cRetVal AS LONGCHAR NO-UNDO.
    DEFINE VARIABLE cNotes AS LONGCHAR NO-UNDO.
    cNotes = "<![CDATA[" + THIS-OBJECT:Notes + "]]>".
    srvc = EWSService:GetService().
    hHandle = srvc:CalenderAPI.
    RUN CreateAppointment IN hHandle
       (INPUT srvc:ExchangeServer,
        INPUT srvc:Domain,
        INPUT srvc:UserName,
        INPUT srvc:Password,
        INPUT THIS-OBJECT:Subject,
        INPUT THIS-OBJECT:Location,
        INPUT THIS-OBJECT:StartDateTime,
        INPUT THIS-OBJECT:EndDateTime,
        INPUT cNotes,
        INPUT THIS-OBJECT:ShouldSetReminder,
        INPUT THIS-OBJECT:ReminderMinutes,
        OUTPUT cRetVal).
    parseResponse(cRetVal).
    RETURN TRUE.
END.

The first few lines (88-91) define variables that we will use later. In line 92, we wrap the Notes field in a CDATA node so that we can handle any data that can be put in it. It could contain HTML, XML or any other kind of data. 

Line 93 calls the GetService method on the EWSService object. EWSService is another class that I created and all it does is wrap the processing around the connection information for the Java and Exchange Web Services. It also takes care of establishing the connection to the Java Web Service. In line 94, we get the handle to that Web Service connection and in lines 96 through 107, we make the call to the Web Service and receive the response in the cRetVal variable.

Line 108 takes care of parsing the response so that the ItemID is stored into the appointment object.

That is all there is to it. Now let's take a look at how we call this code. 

AppointmentViewer.cls

Go to the Resources view and right-click on the AppointmentViewer.cls file. From the context menu, select "Open with…->OpenEdge Visual Designer." Your screen should look like this:

The AppointmentViewer class is a .NET style UI with OpenEdge code behind it. Double-click on the "Generate Appointments" button and you will be taken to a section of code in this form that calls the CreateAppointments.p procedure we looked at earlier. The code is in line 81 through 92 of the editor that is now open:

METHOD PRIVATE VOID btnGenerate_Click( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
    CLOSE QUERY qAppointment.
    RUN CreateAppointments.p (INPUT txtSubject:Text, INPUT txtLocation:Text, INPUT txtNotes:Text, OUTPUT TABLE ttAppointment).
    OPEN QUERY qAppointment
        FOR EACH ttAppointment NO-LOCK
            BY ttAppointment.startdate.
    THIS-OBJECT:bindingSource1:Handle = QUERY qAppointment:HANDLE.
    bindingSource1:RefreshAll().
    dataGridView1:Refresh().
    RETURN.
END METHOD.

This code closes the qAppointment quert, which is a query based on the ttAppointment temp-table defined in the ttappointment.i include file. The code then calls CreateAppointments.p which returns the ttAppointment table. The input parameters for this call are derived from the Subject, Location and Notes text boxes that are at the top of the Appointments tab in the AppointmentViewer window. Once the call is complete, we reopen the query, refresh the binding source and data grid so that the data is displayed on the screen.

Running the Appointment Viewer

Now it's time to run the Appointment Viewer. From the OpenEdge Architect Run menu, choose Run->Run as…->OpenEdge Application. If you are asked to save the file, you can go ahead and do so. When you run the code, you should see the screen at left.

Enter the name of your Java Server and make sure you include the port number, which, by default, will be 8080. For these initial runs, you can make the call using localhost for the name of the server.

The other prompts in the top half of the screen are the same as those we referred to in the calls that we made from soapUI above.

Before you generate the appointments, you should make sure that Outlook is open in the background so you can see the effect of the call.

Once you enter the password, the Generate Appointments button is enabled. Go ahead and enter a Subject, Location and some notes and then choose the Generate Appointments button.

If things are working properly, you will see a slight pause and the grid at the bottom of the screen will populate with a list of appointments that were automatically generated for you by the CreateAppointments.p procedure. 

Your populated screen should look something like the following screen. It is possible that you will see a series of numbers in the Item ID column. If you do, there was a problem creating the appointments on the server. If the appointments were created properly, you will see the ItemID populated with very long strings of characters as below:

In Outlook, you should now see a set of 10 appointments that were created that correspond with the dates and times in the data grid in the Appointment Viewer. Select a row by clicking on the gray area to the left of the data grid. When you have selected a row, the entire row will be highlighted an the Get Appointment button will become active. Choose the Get Appointment button and your screen should look like this:

You will note that the data in the AppointmentView dialog that pops up includes data that we do not have in the temp-table. That's because we fetched the appointment from the Exchange Server, not from the local cache. If you compare the appointment with the appointment properties for the corresponding appointment in Outlook, you will see that they match, so go ahead and edit the contents of the appointment in Outlook – something like this:

Now save and close the appointment in Outlook and give yourself a good 10 to 15 seconds so that Exchange has a chance to let the Client Access Server know about the change, then close the AppointmentView dialog by choosing the OK button, and open it again by choosing the Get Appointment button. The changes that you made in Exchange will now show up in the Appointment View dialog:

Finally, choose the Delete button in the AppointmentView dialog, and the appointment will be removed from the calendar:

If you go and look at the Deleted Items folder in Outlook, you will find the deleted appointment there.

Get Appointment and Delete Appointment

Close down the AppoinmentViewer and go back to OpenEdge Architect. If you go to line 100 of the code for the AppointmentViewer.cls class, you will find the code that fetches the appointment from the server. The code determines which line was highlighted in the data grid and obtains the ItemID from the data grid. It then uses that ItemID to create a new appointment object and the Appointment class calls GetAppointment in the constructor. GetAppointment, which is in line 70 of Appointment.cls simply calls the Java Web Service to get the information.

When it is done, the AppointmentView dialog is displayed with the contents of the Appointment object.

If you right-click on the AppointmentView (not AppointmentViewer) class in the Resources view and you choose "Open With…->OpenEdge Visual Designer", you will get the AppointmentView dialog opened in OpenEdge Architect:

If you now double-click the Delete button, you will see the code that calls DeleteAppointment on the Appointment class. In the Appointment class, this code simply calls the DeleteAppointment operation on the Java Web Service.

Summary

That's it. The code that does all of this is fairly simple and straight-forward, once you understand what it is doing. Most of the complexity associated with this code is really around the communication between Java and the Exchange Server. The OpenEdge connectivity is reasonably simple because the Java code handles the complex work.

This is just the beginning of a prototype that we will expand on over the next few articles. I hope this has been helpful and interesting. Feel free to dig into the code that is supplied. 

In the next article, we will dive into Exchange Impersonation.

I also know that a lot of people are very interested in this, based on the comments that I have have in off-line posts and in response to the survey for the OpenEdge client stuff, and I really don't want to neglect those of you that have asked about it. So I'm compromising, and hopefully this will provide enough information for those that care.

This is part 1 of a multi-part series that will cover the process of connecting to Microsoft Exchange Web Services, submitting requests to Exchange, receiving notifications from Exchange,  creating appointments, tasks, and e-mail, and using Exchange Impersonation. There will also be OpenEdge examples interspersed within it. Each part in the series will have a downloadable zip file with the code in it that actually runs (at least in my environment). 

This post is going to talk about the series of posts and get you set up to start working with it. I am assuming very little, so if you find that things are pretty boring, or you know how to do something, feel free to skip ahead.

Background

In the article that I wrote on the subscription API, I walked through the way that subscription model works. Over the course of this series of articles, we are going to build the Java EWS Web Service and the Java HTTP Servlet.

We'll be running the code on our local workstations so that you don't need a Linux installation.

My interest is in exposing this API to OpenEdge, so I will also be providing some prototype code that shows the OpenEdge EWS API and the ABL Event Handling, although I expect that the majority of Java developers will not really be interested in this.

As my interest is in a service-oriented solution, I also have to concern myself with the complexities of things like Exchange Impersonation which allows a domain user to act on behalf of other users.

There are a lot of moving parts in this prototype so this article will focus on how you go about configuring your environment so you are ready to work through the examples I will be building in the remaining parts. At this point, I don't know how many parts there will be to this series. I know that I will have at least the following articles:

• Part 1 – Introduction and Setup (this article)
• Part 2 – Creating an Appointment
• Part 3 – Using Exchange Impersonation
• Part 4 – Setting up a Subscription
• Part 5 – Getting User Availability
• Part 6 – Creating a Task
• Part 7 – Creating an E-Mail 

Needless to say, this list may change, but I know I need to cover these areas. There are likely to be more further down the line. 

Setup

The rest of this article is dedicated to helping you get your environment set up so that you can work through the examples in the rest of the series. There are several things that you need to have running, and some of them I am going to take for granted that you have set up. For example, I am not going to walk through setting up your OpenEdge Architect environment or your Windows Server/Microsoft Exchange Server configuration. Those are your problems to resolve.

Later, when we get to Exchange Impersonation, I am going to walk you through how to set up an impersonation account, but that is not part of this initial set up. For this initial setup I will assume that you have a working Microsoft Exchange Server that you can get at and play on it. I suggest asking your Exchange admin to create you three or four recipient mailboxes for experimentation. I have four that I created:

• Freddie F. Frogg (froggf@example.com)
• Harriet H. Hippo (hippoh@example.com)
• Edward E. Elifant (elifante@example.com)
• Gerald G. Gerarf (gerarfg@example.com)

I also have an Exchange Impersonation account (ewsproxy@example.com) that I will be using for Exchange impersonation later. Don't worry about this account just yet. We'll get to it later.

So here is the list of software that you need to install to get things going:

• Microsoft Exchange Server 2007 – This code should work with the first 2007 commercial release. I ran and tested against 2007 Service Pack 2. There is nothing special in this code, though. I'll talk more about Exchange Configuration a little later.
• Java EE6 and Glassfish V3 – This is a really simple installation process. All you need to do is set it up with its default parameters, and you should be good to go.
• soapUI 3.5 – You will need this to prove that the Web Service is working.
• OpenEdge 10.2B – installed on a client and on an AppServer. You will need a full AppServer license as the one that comes with OpenEdge Architect does not allow remote connections if my memory serves me right.
• Eclipse for Java EE – All the Java code is built inside Eclipse (3.5.2) with the Java EE IDE feature (1.2.2.2). I have the Web Tools Platform (3.1.1) installed as well. As I always install this with Java EE, I'm not sure how much of this is used. There is also a Glassfish plugin for Eclipse EE that you really should install as it makes testing so much easier.
• OpenEdge Architect or Eclipse pointing to the OpenEdge Architect plugins.

Update: Since I wrote this article, I have installed and tested Microsoft Exchange Server 2007 SP3 and Microsoft Exchange Server 2010. There is one minor modification you will need to make to the sourced code that accompanies this article for it to work with these. Line 132 of the source code file "EWSTest.java" that accompanies this article reads:

ewsConn.setRequestProperty("Content-type", "text/xml;utf-8");

It may need to be changed to read:

ewsConn.setRequestProperty("Content-type", "text/xml;charset=utf-8");

Because so many of you are OpenEdge developers who have little to no experience with Java, and because this solution is predicated on a Java connection, I am going to spend some time walking through the setup of your Java install. Once we have walked through the Java install, I am going to point out how to resolve several problems that you are likely to encounter. So the rest of this article covers:

• Installing Java EE6 and Glassfish
• Installing Eclipse EE and setting it up to work with Glassfish
• Fixing certificate problems
• Changing the EWS folder permissions
• Running a quick test to prove it all works

Let's get started.

Installing Java EE6 and Glassfish

The Java EE6 and Glassfish installation is a reasonably simple installation. Before you install Java EE6, though you need to make sure you have a Java SE6 JDK (not just JRE) installed. If you do not have an SE6 JDK installed, download and install it. Accept all the defaults during the install and it will be installed in C:\Program Files\Java\jdk1.6.0_xx. If you are running a 64-bit version of Windows, the JDK will be installed in C:\Program Files (x86)\Java\jdk1.6.0_xx.

Once you have installed the JDK, go ahead and download and install the Java EE6 and Glassfish V3 Application Server. The install is also a fairly easy installation. Just make sure that as you go through the install, you point the code at the JDK that you just installed. Also, make sure you remember the password for the admin user because you will need it later. My own install of Glassfish is in C:\Apps\GlassfishV3. 

Once you have installed Glassfish, a new program group will be added to your Programs folder called "Java EE 6 SDK". Find this group, open it, and choose the "Start Application Server" option. Once the server has started (the command window will disappear), double click on the "Administration Console" and your browser will open the Glassfish Enterprise Server Administration Console.

Once the Administration Console has run, login using the admin user and password. Assuming your login works, things are as good as they can get for now and we will test it later. The next step is to install the Eclipse Enterprise Edition and configure it to work with Java. 

Just before we do that, go back to the "Java EE 6 SDK" program group, and choose the "Stop Application Server" option.

Installing Eclipse EE and setting it up to work with Glassfish

The next step is to download and install the Eclipse IDE for Java EE developers. This is a 190MB download so it takes a little while if you are on a slow line. Once you have downloaded it, install it by unzipping it into a directory (for me, C:\Apps\Eclipse\EclipseEE). Create a shortcut to the "eclipse.exe" file that is in the "eclipse" directory under your install path.

Now go ahead and start Eclipse for the first time. When you do, you will be prompted for a workspace. Choose a path to a new, empty directory. You will then be presented with the "eclipse Java EE ide" welcome screen. Click the "Workbench" icon in the top right corner of the screen.

The next thing to do is make sure that you have the latest patches. From the Help menu, choose "Check for Updates".

Setting the default Java Runtime Environment

The next step is to set up Eclipse to use the Java JDK that you installed a little earlier. From the Eclipse "Window" menu, choose "Preferences" (the last menu option). In the tree on the right of the Preferences window, expand the "Java" node and select "Installed JREs". 

Choose the "Add…" button on the right side of the "Installed JREs" pane and you will be presented with a dialog entitled "Add JRE". Select "Standard VM" in the selection list and choose the "Next >" button.

On the "JRE Definition" wizard page, select the "Directory…" button and navigate to the install directory for the JDK that you installed above (normally C:\Program Files\Java\jdk1.6.0_xx). Choose the OK button and the Finish button on the wizard page and you will be returned to the Preferences page.

In the list of installed JREs, make sure that the new JDK that you just added has a check mark to the left of it so that it becomes the default JRE for Eclipse. Choose the OK button for the Preferences page, and we are done with the JDK setup.

Setting up Eclipse to work with Glassfish

The next step is to configure Eclipse so that it is easy to deploy code to the Glassfish server. At the bottom of the Eclipse window is a tab entitled "Servers". Select this tab. Right-click inside the pane for the Servers tab, and select "New->Server". Just below the "Server's host name" prompt is a hyperlink entitled "Download additional server adapters". Select this link.

In the "Install New Extension" dialog, select "Glassfish Java EE5, Java EE6" and choose next. Complete the wizard, and the Glassfish adapter will be installed. Once it is installed, you will be presented with the New Server dialog.

Make sure you select the "Glassfish V3 Java EE 6" option from the Glassfish folder, and choose the "Next >" button.

On the next page, select the JDK JRE that you set up earlier and make sure to point the Application Server Directory to your Glassfish install directory. Note that under the directory that you installed Glassfish, there is a subdirectory called "glassfish". You need to be pointing at that directory.

On the next page of the wizard, you are asked for the user name and password for the administrator. As this is a development machine, go ahead and specify it and check the "Preserve Sessions across Redeployment" flag. You can then go ahead and choose the Finish button and the New Server Wizard will close. In the Servers tab, you should now see a entry entitled "GlassFish v3 Java EE 6 at localhost".

Select the server that you just added, and choose the green and white arrow button in the toolbar at the top right of the "Servers" pane. Eclipse will automatically switch to the Console tab and you should see output like the following in that pane:

Waiting for DAS to start ..........
Started domain: domain1
Domain location: C:\Apps\glassfishv3\glassfish\domains\domain1
Log file: C:\Apps\glassfishv3\glassfish\domains\domain1\logs\server.log
Admin port for the domain: 4848
Command start-domain executed successfully.

If you now switch back to the "Servers" pane, right-click on the "GlassFish v3 Java EE 6 at localhost" line, and choose "GlassFish Enterprise Server -> View Admin Console", you should end up with a window as above. Your GlassFish Server now works from inside your Eclipse EE environment.

Fixing Certificate Problems

The first problem you are likely to run into with Exchange Server is a certificate related issue with your Exchange Web Server. To figure out if this is a problem, make sure that you can get at the Exchange Web Services WSDL. The Exchange Web Service is installed by default on the Client Access Server (CAS). Ask your Exchange Administrator for the name of this machine. The URL to the WSDL is:

https://exchange.cas.server/ews/Services.wsdl

If you type this URL into Microsoft Internet Explorer, you may get a certificate error as shown in this screenshot. If you get this error, you need to import this certificate into your browser's certificate store and you need to add it to the Glassfish certificate store, too.

Importing the certificate into the browser's certificate store

You need to choose the "Continue to this website" link if you see this and when you do you will be prompted to log in. After logging in with your domain username and password, you will see a page full of XML with a certificate error in the title bar. Right-click in the pane that contains the XML, and choose "Properties". You will be presented with a dialog with a "Certificate" button at the bottom right. Choose the "Certificate" button and you will arrive at the following dialog:

Your certificate will likely have different information in it. What I am going to recommend right now is not the way that I would do this in production. Right now I am working around a problem that you need to deal with to be able to make this stuff work. In production, you really do need to set up a trusted certificate authority within the organization, but that is way beyond the scope of this article.

The next step is to choose the "Install Certificate" button above. This will start the "Certificate Import Wizard." You will need to install this certificate in the "Trusted Root Certification Authorities" Certificate Store. Page 2 of the Certificate Import Wizard contains a radio-set that allows you to select where to install the certificate. Choose the "Place certificates in the following store" option and then choose the "Browse…" button. You will then be presented with a dialog that allows you to select the certificate store.

Choose the "Trusted Root Certification Authorities" entry and choose the OK button. Finish going through the wizard and you will eventually be presented with the following dialog (or something a lot like it):

Choose the "Yes" button and the certificate will be installed for you. Close down your browser, open it up again, and try and navigate to the URL above again. This time you should not see the Certificate Error message that we saw above and you should be able to log in and get to the WSDL. 

Exporting the certificate

We're not done with the certificates yet, though. The next thing we have to do is export the certificate from the certificate store so we can load it into Glassfish's certificate store. With Internet Explorer open, choose "Internet Options" from the "Tools" menu. When the Internet Options dialog opens, select the "Content" tab as below:

Choose the "Certificates" button in the middle of the dialog and you will be presented with the "Certificates" dialog. Choose the "Trusted Root Certification Authorities" tab and scroll down and select your certificate from the certificate store:

Now choose the "Export" button as you will need to create a certificate file that can be imported into the Glassfish certificate store. The "Certificate Export Wizard" will now be presented and you should choose the "Next" button, making sure to select the "DER encoded binary X.509 (.CER)" option:

Finish off the wizard by selecting a destination in which to store the certificate file. 

Importing the certificate into the Glassfish certificate store

To import the certificate into the Glassfish certificate store, open a command line prompt and change directories to the directory in which Glassfish is installed. I installed it at C:\Apps\Glassfishv3. Once in that directory, issue the following command (I am assuming that the Java/bin root directory is in your path): 

cd glassfish\domains\domain1\config
keytool -importcert -v -trustcacerts -keystore cacerts.jks -file c:\<pathtocertificate>\<certificatefile>.cer

You will be prompted for a password. If you have never changed the password for the certificate store, the password defaults to "changeit". Import the certificate into the store, and you should be almost ready to start using Glassfish to communicate with the Exchange Web Service.

Change EWS folder permissions

The next step to making this code function is to change the permissions on the EWS folder on the Microsoft Exchange Client Access Server to which you will be connecting. This requires administrative privileges on the server.

Warning: I do not recommend that you do this on your production Exchange Client Access Server, especially if it is an internet-facing server. Making this change significantly changes the security level of your Exchange server and could make it vulnerable to attack. I have a test Exchange server specifically set up for this.

Run the "Internet Information Services (IIS) Manager" tool (also accessible from Server Manager as shown below. Assuming your server is named EXCHANGESERVER, expand the EXCHANGESERVER node. Under it you will find a "Sites" node. Expand that and the "Default Web Sites" node under it. Under that you will find an "EWS" folder. Select that folder.

In the "/EWS Home" pane that now opens, there is an icon for "Authentication" in the "IIS" group of icons (In the above screenshot, it is the third icon from the bottom on the left of the pane). Double-click this icon and the pane will change to look like this:

 .

In the Authentication pane (the new pane) there is one item that you need to change. Click on the line that says "Basic authentication" and then right-click on it. This line should currently have the word "Disabled" in the "Status" column. In the popup menu that now displays, select "Enable".

That should do it. The configuration changes you have now made should work for you.

Running a quick test to prove it works

As I mentioned earlier in this post, you are going to need soapUI to be able to do any testing, so if you have not done so, now would be a good time to download and install soapUI. Once you have done that, the other thing you will need is a zip file that you can download here that contains a sample Web Service to test the communication with Exchange Web Server.

Once you have the zip file downloaded, start Eclipse EE. In the "Project Exporer" pane at left, right-click and from the context menu select "Import -> Import…" and the "Import" dialog below will appear. Expand the "General" folder and select "Existing Projects into Workspace" and choose the "Next >" button.

On the next page of the Import wizard, choose the "Select archive file" radio-set and browse to the zip file that you just downloaded. In the "Projects:" selection list, make sure that EWSTest is checked and choose the Finish button.

If all is good, there will be no little red and white "x" on the EWSTest project. If there is, it's probably because the JDK version that you have installed is different from the one I am using. To fix that, right-click on the EWSTest project and select "Properties" from the context menu. In the Properties window, select the "Java Build Path" property set and choose the "Libraries" tab. Select the "JRE System Library" and then choose the Remove button. Now choose the "Add Library…" button, select "JRE System Library" in the "Add Library" wizard page and choose next.  Make sure the "Workspace default JRE" is selected and choose the "Finish" button. Choose OK on the Properties page and the little red and white "x" should disappear.

Now that you have a properly compiled version of EWSTest project, you need to start your Glassfish server if it is not already running. Drag the EWSTest project from the Project Explorer pane to the "GlassFish v3 Java EE 6 at localhost" entry in the Server pane. If you expand the Glassfish node in the Server pane, you should now see "EWSTest [Synchronized]" under the GlassFish node as follows:

Now comes time to test it all out.  Make sure you leave Eclipse running – we need that Application Server. Now go and start soapUI, and right-click on the "Projects" node in the Navigator. From the context menus choose "New soapUI Project".

In the "Initial WSDL/WADL:" prompt, type the following:

http://localhost:8080/EWSTest/EWSTestService?wsdl

Choose the OK button and soapUI will create a project for you called EWSTestService. Expand the CreateAppointment node and under it there is a Request 1 node. Double-click the Request 1 node and fill in the contents of the XML pane on the left.

The node in the XML document need to be completed as follows:

• ExchangeServer – The fully qualified domain name of your Exchange Client Access Server that is running your Exchange Web Service;
• DomainUser – Your test recipient account qualified with a domain name – so DOMAIN\user;
• DomainPassword – Your test recipient account's password;
• Description – A description to appear at the top of the appointment;
• Location – A location where the meeting should take place;
• StartDateTime – A date and time at which the appointment should start in the format yyyy-mm-ddThh:mm:ss (the T is required);
• EndDateTime – A date and time at which the appointment should end in the same format as the StartDateTime. Note that if this date and time is less than the start, you will get a "Bad post… 500" error.

Once you have filled all of these fields out, choose the green arrow button – tooltip: "Submit request to specified endpoint URL" – and the call will execute. If it is successful, you will get a SOAP document in the right-hand pane with a "CreateAppointmentResponse" node that includes a "return" node with a CDATA node inside it. The return node is fairly long and includes an "Item" node with "ID" and "ChangeKey" attributes.

Of course, your ultimate test is to login to the test user's account and start Outlook for him. You can celebrate when you see the appointment created:

If you double-click the appointment, you will note that the details have been filled in exactly as you would expect:

Caution: The test code that I included here could cause you some trouble if you try and create appointments in different users' calendars without restarting the Glassfish server in-between. It won't do that and we'll get into why in one of the next posts. Just be careful not to use this to mess up real calendars inadvertently.

Summary

At this point you have a working Exchange Web Services call happening from Java. This is the first step. In the next part to this series, we will walk through the code that actually creates the appointment to understand what it is doing. That code will be commented to help explain what it does.

Please feel free to leave any comments you may have and please let me know if you run into problems with the instructions that I have given here.

It took me a while to get this done, not so much because of the code, but because the documentation that accompanies it is pretty extensive and I have been in the middle of some significant career changes.

This post is long primarily because I walk through the highlights of the what the code does and how this bolsters what I was saying in my earlier post.

Inside the zip file are 2 zip files and 3 PDF files:

• DynamicOpenClientJar.zip is the compiled version of the code. It contains a jar file, the input.xml, a batch file, and the Progress source code.
• DynamicOpenClientJar.pdf contains setup instructions to set it up and run it.
• DynamicOpenClientSrc.zip is the source code.
• DynamicOpenClientSrc.pdf contains the instructions that that tells you how to set the source code up to work with Eclipse.
• DynamicOpenClient.pdf is a detailed tour of the code and describes how it works.

This is Sample Code

Before you dig into the code and say "Wow!! This code sucks!!" it is important to understand that this is sample code. There are a lot of things about it that are ugly. Some of the object model needs serious refining. There are cleaner ways of doing the XML parsing and it is nowhere near as defensive as it should be. There are those who believe that bad code samples lead to bad code in production, but there is another line of thought that goes that if you don't recognize those bad examples, you should not be coding to start with. The point with this code is that it demonstrates concepts and that's what it was intended to do.

Code Limitations

For the sake of brevity, I have deliberately not covered stuff like supporting supporting ProDataSets and all of the different Progress data types. I have covered the most common ones and temp-tables. ProDataSets are really an extension of temp-tables and you can feel free to go and look at the code in a generated proxy to see how they work. I also stopped short of supporting the building of temp-tables from an input XML file. The extra code to do this did not seem like it would really add that much to the example. This code example also does not support persistent procedures because they are a lot more complicated than this code will allow.

Set it up and try it

Having said all of that, I wanted to spend some time in this post elaborating on the comments that I made in the earlier post about why Dynamic OpenClient is such a powerful technology, using the example code that I am presenting here. So I am going to assume for the rest of this article that you have at least set up and run the example and that you have the source code accessible to follow along.

How it Works

The Dynamic Open Client code takes an XML file and parses it for AppServer connection parameters, R-Code signatures and calls that need to be made to the Progress/OpenEdge R-Code files. The sequence diagram at right (click on it for a full-size image) shows the process.

Once the XML file has been parsed, the utility executes each of the calls and serializes the results of the call's execution to an internal XML document. Once all the calls have been executed and serialized, the results are written out to another XML file that is specified in the input.xml file. More information on the XML file's format is in the DynamicOpenClient.pdf file.

The Main Components

To understand how this utility works, you need to understand the core of the class model. So let me start by dividing the class model into its major areas.

You can pretty much ignore the com.tsg.common project. It contains an interface - INamedItem – used by a few classes that simply has a getName() method declaration. INamedItem is implemented by some of the classes in the com.tsg.dynamicopenclient project. This interface is specifically used for objects that may be stored in a com.tsg.common.collections.OrdinalList – a specialized list that is ordinal like an ArrayList, but expects uniquely named items in the list. OrdinalList is used for things like field lists and parameter lists where the fields need to be in a specific order, but the names have to be unique.

The com.tsg.dynamicopenclient project contains three packages:

• com.tsg.dynamicopenclient - This package contains the code that does most of the work;
• com.tsg.dynamicopenclient.data - This package contains the class hierarchy for parameter and other data element definitions;
• com.tsg.dynamicopenclient.valueholders - This package contains the class hierarchy for all the value holders that are used to contain the values of input and output parameters.

Data Types

One of the most important aspects of the communication between the OpenClient and the AppServer, is the mapping of data types from Java to Progress. To make sure that this is done consistently, there is a DataType enumeration in com.tsg.dynamicopenclient. If you have not worked with Java 5, enumerations may be a new concept to you and this one is particularly more so than others. An enumeration is a great way to deal with hard-coded constants and it is particularly useful where a map of constants is necessary. In this particular case we have to map an OpenClient numeric constant to a string representation of the data type, a Java class that can be used to map to that type and a valueholder class that can be used to contain the Java type. The following definition of the INTEGER data type demonstrates the mechanism:

INTEGER
  (Parameter.PRO_INTEGER, // Progress numeric constant
   Parameter.PRO_INTEGER_NAME, // Progress character constant
   "java.lang.Integer", // Java class to be used to map
   "com.tsg.dynamicopenclient.valueholders.IntegerValueHolder"), // Dynamic OpenClient valueholder

The DataType enumeration has several methods associated with it to retrieve a constant based on the string name of the data type or to obtain the Java class, value holder class or Progress data type constant. It also contains code that will instantiate an object of either the Java class to contain the data type or the value holder. This enumeration truly is at the core of the code.

Data Elements

The com.tsg.dynamicopenclient.data package contains a set of classes that define the behavior of data elements. A data element is any item that has a name and a datatype associated with it. Thus, fields and parameters are all data elements. Data elements only store the definition of the element. They do not store the value. The value is stored in a value holder. The abstract base DataElement class contains all the behavior for parsing parameter and field definition information from an XML node.

The Parameter class extends it by providing support for parameter modes (INPUT, INPUT-OUTPUT and OUTPUT) which are mapped in an enumeration called ParameterMode in com.tsg.dynamicopenclient.

The TempTableParameter class extends the Parameter class further by providing support for parsing temp-table definitions from the source code and supporting the construction of ProDataGraphMetaData objects that are used to build the ProDataGraph to transport temp-tables between AppServer and client.

Value Holders

The com.tsg.dynamicopenclient.valueholders package contains a set of classes and an interface that are used to standardize the way that data types are dealt with. Looking at the class model, the value holder hierarchy is to the right of the diagram. This hierarchy leverages the concept of generics that was introduced in Java 5.

The IValueHolder interface is the base of the hierarchy and the ValueHolder abstract class contains the generic behavior for value holders. These classes provide support for the Progress UNKNOWN value as well as reasonable default values that match the Progress defaults for its data types.

Value holders are used to set the value of input parameters and to contain the values of output parameters.

DynamicOpenClient Class

The DynamicOpenClient class in com.tsg.dynamicopenclient contains the main() method - the entry point to the utility. It starts out by parsing the parameters to determine where the XML file is that contains the signatures and input parameters for the calls. The input.xml file's structure is detailed in the DynamicOpenClient.pdf file that accompanies the source code. In essence, though, there are 4 types of nodes that are important:

• dynamicoc – This is the root node for the document and it contains an OutputFile attribute that has the name of the file that should be used for the results of the calls.
• appserver – This node contains the signature and call nodes and a set of attributes that define the connection parameters for the AppServer.
• signature – This node contains the signature of a call that will be executed against the AppServer. The signature node may contain a set of parameter nodes which will be all of the parameters for a procedure. These parameters must be specified in the order that they are specified in the ABL source code. If the parameter's DataType attribute is TABLE, the node will contain child nodes that are the field and indexes for the table.
• call – This node contains a list of calls that need to be executed against the AppServer. Each of them should refer (by means of the Procedure attribute) to a previously specified signature. call Nodes may contain subordinate parametervalue nodes that reference a parameter in the signature by name and specify the value to be used as the input value for that parameter.

The following code extract comes from the main() method.

//Extracted from main() method.
//

//Instantiate the CallManager
CallManager manager = CallManager.getInstance();

//Parse the XML file.
try {
	parse(fileName);
}
catch (Exception e) {
	System.out.println(e.getMessage());
	return;
}
.
.
.
Iterator<Call> iter = manager.iterator();
while (iter.hasNext()) {
	Call call = iter.next();  //Get the call
	call.executeCall();   //Execute the call
	outRoot.appendChild(call.serializeResults(outputDocument));
	iter.remove();
}
.
.
.
try {
	writeResults();  // Write the XML results file out to disk.
}
catch (Exception e) {
	System.out.println(e.getMessage());
	return;
}

Before doing anything else, the code instantiates the Singleton CallManager to hold onto all the data that will be parsed from the XML file.

The main() method calls the static parse() method with the name of the XML file to be parsed. This method parses the XML document and iterates through the four element nodes mentioned above. It also sets up a DOM document that will be used as the output document for the results of the calls.

For each element, it instantiates an object of the appropriate class and passes it the XML node that needs to be instantiated. This object is then added to the CallManager where it will be retrieved later.

//Extracted from parse() method.
//
Node elementNode = null;
while((elementNode = iterator.nextNode()) != null) { // Loop through elements

	// Handle root node.
	if (elementNode.getNodeName().equalsIgnoreCase(XMLStrings.INPUT_ROOT_NODE.toString())) { 	

		// Setup the output file.
		String attrValue = XMLStrings.getAttribute(elementNode, XMLStrings.OUTPUT_FILE_ATTR.toString());
		if (attrValue != null) {
			outputFileName = attrValue;
		}
	}

	// Handle appserver node
	if (elementNode.getNodeName().equalsIgnoreCase(XMLStrings.APPSERVER_NODE.toString()) ) {
		manager.setAppServerConnection(new AppServerConnection(elementNode));
	}

	// Handle signature node
	if (elementNode.getNodeName().equalsIgnoreCase(XMLStrings.SIGNATURE_NODE.toString()) ) {
		manager.setSignature(new Signature(elementNode));
	}

 	// Handle call node
	if (elementNode.getNodeName().equalsIgnoreCase(XMLStrings.CALL_NODE.toString()) ) {
		manager.addCall(new Call(elementNode)); 
 	}
}

The CallManager implements the Iterable interface for the Call class. Back in the main() method, the next thing we do is iterate through all of the Call objects in the CallManager and we execute the call. This is where the real work happens and a description of it is below. When execution is complete, the parameter values will have been stored in the Call object and a call to serializeResults() will return an XML node that can be appended to the output document. The Call object is then deleted from the list of calls to free up the memory that any temp-tables will occupy.

Once all the calls have been executed, a call is made to writeResults() which writes the output XML document to disk.

Executing the Call

A call is actually executed by a call to executeCall() on the Call object. The executeCall() method simply builds a parameter array, calls the runProcedure() method on the AppServerConnection object, builds the output parameter value set and handles any exceptions. The thing that makes this client dynamic is the code in buildParamArray() and buildOutputValues().

buildParamArray()

In order to make a call to the AppServer, the OpenClient needs a procedure name to call and a parameter array (com.progress.openABL.javaproxy.ParamArray) for the call. The parameter array needs to contain a full description of each parameter as well as the value to be set for the parameter. The Call object has a procedure name and it has the values of the input parameters. The name of the procedure maps to a Signature object which can be obtained from the CallManager and it contains the definitions of all of the parameters that are needed for the call. Thus, buildParamArray() obtains the Signature object and builds a ParamArray object with each of the parameter definitions in the Signature object. As it attempts to add each parameter to the ParamArray, it obtains a IValueHolder object to contain the parameter's input or output parameter value. It then checks for a corresponding input value in the Call object. If it finds a corresponding value it sets the input value in the ParamArray from this value. This is how the Call information in the XML file can specify the parameter values by name in any order and only specify the ones that have values associated with them.

//Extracted from buildParamArray() method.
//

CallManager manager = CallManager.getInstance();
Signature sig = manager.getSignature(getProcedureName()); //Get the signature for this call
if (sig == null) {
	throw new DynamicOpenClientException(...);
}
ParamArray params = new ParamArray(sig.getParameterCount()); //Instantiate a ParamArray object

int idx = 0;

// Iterate through all the parameters in the signature.
for (Parameter param : sig) { 

	// Instantiate an IValueHolder for this data type.
	IValueHolder<?> valueHolder = DataType.getValueHolder(param.getDataType());
	paramValues.add(valueHolder); // Put the value holder into the paramValues list.

	// If we can find a parameter value that was set for this call,
	// set the value of the IValueHolder to the input value.
	if (inputValues.containsKey(param.getName())) { 
		valueHolder.setObject(inputValues.get(param.getName()));
	}

Now that the data we need is available (ie, the parameter type information and input values have been set), we can go about setting the values, but we need to treat the TABLE and TABLE-HANDLE types differently from the the other data types. The reason is that they need a ProDataGraph and its metadata. The code for setting the values is therefore as follows:

Object value = null;
switch(param.getDataType()) {
	case TABLE:
	case TABLE_HANDLE:
		TempTableParameter ttParam = (TempTableParameter) param;
		ProDataGraphValueHolder graphHolder = (ProDataGraphValueHolder) valueHolder;
		ProDataGraphMetaData metaData = null;
		switch(param.getMode()) {
			case OUTPUT:
				// For a table we need the table structure. TABLE_HANDLE needs null.
				if (param.getDataType() == DataType.TABLE) {
					metaData = ttParam.getProDataGraphMetaData();
				}
				break;
			default:
				value = graphHolder.getProDataGraph();
				metaData = graphHolder.getProDataGraph().getMetaData();
				break;
		}

		// Add a parameter to the ParamArray with the appropriate value.
		params.addParameter(idx, value, ttParam.getMode().getModeCode(),
			ttParam.getDataType().getTypeCode(),
			ttParam.getExtent(),
			metaData);
		break;
	default:
		// Now get the object from the IValueHolder that has the value in it.
		value = valueHolder.get(); 

		// Add a parameter to the ParamArray with the appropriate value.
		params.addParameter(idx, value, param.getMode().getModeCode(),
			param.getDataType().getTypeCode(),
			param.getExtent(),
			(ProDataGraphMetaData) null);
		break;
}

The outer switch in this code handles the difference between TABLE, TABLE-HANDLE and other parameters. So skip the first cases and look at the default case (the last 11 lines of this code block from the word "default:" on. All this code does is grab the object that is in ValueHolder and assign it to the value variable. It then adds a parameter specifying the ordinal position (idx), the value, the parameter mode (INPUT, OUTPUT or INPUT-OUTPUT), the Progress DataType Code from the DataType, the extent and a null for the ProDataGraphMetaData.

The TABLE and TABLE-HANDLE cases are slightly more complicated. For a TABLE or TABLE-HANDLE if the parameter is either an INPUT or INPUT-OUTPUT parameter, the value has to be set to the ProDataGraph that will be used to contain the return value. The ProDataGraphMetaData needs to be specified to supply the table structure. In the case of an OUTPUT parameter, a TABLE parameter requires ProDataGraphMetaData but null in the value parameter and in the case of a TABLE-HANDLE, both the metadata and the value need to be null. In both cases, the Parameter object will have been specialized as a TempTableParameter object so that it could build the temp-table structure.

Once the parameters have all been added to the ParamArray, it is returned to the caller (executeCall) and is now ready to invoke the call.

runProcedure()

The runProcedure() method call is run on the AppServerConnection object that is contained in the CallManager. The AppServerConnection class performs 2 functions:

1. It stores the AppServer connection parameter values; and
2. It executes calls against the AppServer.

The first thing runProcedure() does is call obtainAppObject(). The OpenAppObject class provides access to AppServer connections from the connection pool and supports all communication with the AppServer. The obtainAppObject() call instantiates a Connection object and then an OpenAppObject if they have not already been instantiated. This establishes the connection to the AppServer.

Once the connection is established, the runProc() method on the OpenAppObject is run with the ParamArray that was passed in and any exceptions are thrown back to the caller. If this code completes successfully, the AppServer call has succeeded.

buildOutputValues()

After the call has completed, executeCall() calls buildOutputValues() with the ParamArray that was used in runProcedure(). 

//Extracted from buildOutputValues()
//
returnValue = params.getProcReturnString();
if (returnValue == null) {
	returnValue = "null/Unknown (?)";
}
int idx = 0;
for (Parameter param : sig) { // Loop through each parameter in the signature.
	switch (param.getMode()) { // Check the parameter mode.
		case INPUT_OUTPUT:
		case OUTPUT:

			// Get the value of the parameter from the paramArray.
			Object outputValue = params.getOutputParameter(idx); 

			// Set the value of the parameter in our internal array to be the result
			paramValues.get(idx).setObject(outputValue);
	}
	idx++;
}

The buildOutputValues() method does 2 things:

1. It obtains the value of the RETURN-VALUE string from Progress; and
2. It loops through all OUTPUT or INPUT-OUTPUT parameters and sets the value in the IValueHolder from the value in the ParamArray.

The output parameter values are thus available to the Call object for serialization. 

Why this is so powerful 

That is the crux of the code in the Dynamic OpenClient Sample Utility. It's not really that complicated and although this is a crude example, it does show the relative ease with which one can build a client that invokes calls for which all signature information is obtained at runtime.

If you work through the associated document that contains a description of running the utility, you will notice how easy it is to edit the ABL code and change temp-table structures or any other signature related information, modify the corresponding signature in the XML file and re-run the utility without changing the Java code.

If you go ahead and automate the generation of the XML signatures into a post-compile operation and post it on a web-server or some other centralized resource, there is never a need to change the Java code unless you discover a bug in it or Progress adds a data type.

There's another interesting side effect to this. It would not take much effort beyond this to build an automated mechanism for dynamic WSDL generation so that you dynamically expose any ABL procedure as a WebService. Taking it further, exposing it as an EJB or J2EE container or a JMS endpoint would be fairly simple too and would mean very little would ever need to be changed in the plumbing between the client and the server. You see, as far as I am concerned, everything related to ProxyGen is plumbing that should never require a recompile unless the underpinnings change. ProxyGen forces that each time a temp-table definition is changed.

Hopefully this example is useful. I am planning a .NET equivalent later on.

In order for the OpenClient to be able to connect to the AppServer, make a call and return the output parameters, there is a certain amount of code that you need on the client (Java or .NET) that wraps the OpenClient library. In an effort to simplify the process of writing that code, OpenEdge includes a utility called "ProxyGen" that parses the OpenEdge ABL code and generates a proxy class that wraps all of the code needed and exposes it as a simple method call. Once you have generated the proxy, you simply include the generated class in your code (either as a .jar or a .NET assembly, or even directly as source code) and you can make whatever call you need.

The problem with ProxyGen is that you have to regenerate the proxy and potentially rebuild the client each time the ABL procedure changes its signature. That would be okay if the ProDataset and Temp-Table definitions were not part of the signature, but they are and adding a field to a temp-table should not cause a proxy to break.

"Hang on, Bruce," I can hear you say, "Why is the signature of the temp-table not a change to the signature to the API?" I'm not saying that it isn't, but I am saying that it is far more difficult to avoid making this mistake. Here's why:

Typically, temp-tables that form part of the in-memory data model are defined in include files and then used in procedures and classes as in the attached diagram.

Let's assume that Procedure1.p and Procedure2.p are deployed to the AppServer and that Procedure1.p accepts the temp-table as an input parameter and Procedure2.p uses it as an input-output parameter.

As a result of a necessary change to the in-memory data model, a field or two are added to the temp-table definition for the purposes of the Class1.cls and Class2.cls.  As part of the build, the code is recompiled and the new code deployment to the AppServer is completed successfully. Note that there has been no planned change to the Procedure1.p and Procedure2.p.

The problem that we now face is that the proxies that were generated for the Procedure1.p and Procedure2.p are now invalid. The temp-table definition is no longer correct and a run-time error will now occur for the client when these procedures are called.

Another problem with proxies is the complexity associated with unit-testing and verifying each individual proxy. Each time a proxy is changed, each of the unit tests for each call in the proxy has to be rerun and retested. There is no way to generically test them to verify the Java/.NET code.

In one of the more recent versions of OpenClient, the API that the OpenClient uses is documented so that it is now possible to dynamically construct the proxy calls at run-time. The overarching benefit in this lies in the ability to now define the temp-table definitions on the fly. The Java/.NET code can now define the temp-table dynamically at run-time so that if a change is made to the definition, the client can deal with the change with no impact on the OpenClient source code.

This functionality is, in fact, so powerful that the entire signature, including all parameter definitions, can be discovered and defined at run-time.

This concept becomes even more interesting as you consider using it for WebServices. ProxyGen can generate the WSDL for a procedure that is to be exposed as a WebService, although it suffers from the same issues if the signature changes. The dynamic OpenClient API makes it possible to dynamically generate the WSDL at run-time from the procedure. Obviously there are overheads associated with auto-discovering a procedure's signature. It makes sense, therefore, to build out this functionality so that the signature discovery is done as seldom as possible.

In a future article I will provide some code samples that show you how to use the Dynamic OpenClient.

UPDATE: I have subsequently made this code sample available. You can refer to it here.