This page presents an introduction to the Java Bridge to Exchange product. You'll learn the basics on how to configure and use the library with your Java application.

Installation

The Java Bridge to Exchange library classes are packaged in a single JAR file named « jbex-v1.4.8-eval.jar ». The downloaded package contains a folder named « lib » which contains this JAR file.

You have to add the JAR file to your application's CLASSPATH. The CLASSPATH is the path that the Java runtime environment (JRE) searches for classes and other resource files. There are multiple ways to setup the CLASSPATH depending on your development environment. For example, you can specify the path to the JAR files in the command line when launching your application using the « -cp » option:

> java -cp lib\jbex-v1.4.8-eval.jar ...

For more information about the CLASSPATH, have a look at Sun's documentation: http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/classpath.html

Using the library

The starting point to access Exchange is creating an Exchange object:

// Creating the Exchange object connects to the Exchange server
// with the supplied credentials.
Exchange exchange = new Exchange("hostname","username","password");

Once you created the Exchange object, you have access to Exchange folders, items and data. Look at the JavaDoc for the listing of all methods provided.

Accessing folders

Exchange items are stored in folders. A folder is represented by the ExchangeFolder interface. Folders are stored in a hierarchical structure with one root folder. The Exchange's root folder can be accessed with the method Exchange.getRootFolder(). Sub-folders of the root folder contains Exchange data and items.

An example Exchange folders structure may look like this:

Folder	Returned by method
Root folder	Exchange.getRootFolder
Freebusy Data
Reminders
Schedule
To-Do Search
Top of Information Store	Exchange.getTopFolder
Calendar	Exchange.getCalendarFolder
Contacts	Exchange.getContactsFolder
Drafts
Inbox	Exchange.getInboxFolder
Sent Items	Exchange.getSentItemsFolder
Tasks	Exchange.getTasksFolder
Views

As can be seen in this structure, the most interesting folders containing Exchange messages, contacts and appointments are under the Top of Information Store folder. The following example code lists all sub-folders of this Top folder:

Exchange exchange = new Exchange("hostname","username","password");

// Listing all top folders
for(ExchangeFolder folder : exchange.getTopFolders())
{
System.out.println(folder.getDisplayName());
}

To display all the folders hierarchy recursively, please look at the DisplayFolders.java example application.

Creating new folders

A new folder can be created as a sub-folder of an existing folder. The method ExchangeFolder.createFolder allows to create a new folder. When creating folders, you can specify the kind of items the folder will contain and the folder's display name. Example code:

Exchange exchange = new Exchange("hostname","username","password");

// Creating a new Exchange folder
exchange.getTopFolder().createFolder(FolderContentType.Contacts, "My folder");

Accessing items

The method ExchangeFolder.getItems() returns a collection object providing access to the items stored in a folder.

The collection of items can be iterated over, searched or sorted as required. As a folder may contain a large number of items, the collection is implemented to fetch items from Exchange on demand only when those items are accessed. It also allows to access only a specific portion of items. This is particulary useful for paging mechanisms where only items between specific indexes need to be displayed.

As the items collection implements the Iterable interface, items can be iterated over in a simple foreach statement. Example code:

Exchange exchange = new Exchange("hostname","username","password");

// Get the default Contacts folder
ExchangeFolder folder = exchange.getContactsFolder();

// Display all the contacts in the folder:
for(ExchangeItem item : folder.getItems())
{
ExchangeContact contact = (ExchangeContact) item;
System.out.println("Last name: " + contact.getLastName());
}

The ExchangeItem is the base interface for all Exchange items. Specifically typed items inherit and extend this interface. A typical Exchange item implements one of the following interfaces:

ExchangeCalendarItem	Represents an appointment or meeting
ExchangeContact	Represents a contact
ExchangeMail	Represents an e-mail message
ExchangeTask	Represents a task

The above interfaces expose methods to get and set items properties. In order to save changed properties to Exchange, call the method ExchangeItem.save() on the item object.

Creating new items

A new item can be created in an existing folder. The method ExchangeFolder.createItem allows to create a new item object. The item won't be saved in Exchange until the method ExchangeItem.save() is called.

When creating an item, you need to specify the type of item (Contact, Mail, Task, etc). The following additional methods allow to create specific types of items:

ExchangeFolder.createCalendarItem	Creates an appointment or meeting in a specific folder
ExchangeFolder.createContact	Creates a contact in a specific folder
ExchangeFolder.createMail	Creates an e-mail message in a specific folder
ExchangeFolder.createTask	Creates a task in a specific folder
Exchange.createCalendarItem	Creates an appointment or meeting in the user's default calendar folder
Exchange.createMail	Creates a new e-mail message to be sent out programmatically. The method ExchangeMail.send() is used to send the created e-mail.

Below is an example code that creates a new e-mail and sends it:

Exchange exchange = new Exchange("hostname","username","password");

// Create a new e-mail:
ExchangeMail mail = exchange.createMail();

// Set the recipient, subject and body:
mail.setToRecipient("info@moyosoft.com");
mail.setSubject("Test message");
mail.setBody("Hello. There's a message sent from Java.");

// Send the message:
mail.send();

Searching and sorting items

The static class named « If » can create a restriction object used to search or filter Exchange items. This class contains static definitions for all Exchange item's fields. Each field can be used to apply a specific restriction criteria.

Depending on the type of the field (String, Date, boolean, etc.) a set of methods is available to construct the criteria condition. For example, for String fields, the methods StringField.contains, StringField.startsWith or StringField.isExactly can be used.

Below are a few examples illustrating how to create a Restriction object:

// Matches items with a subject starting with "Test":
Restriction restriction = If.Item.Subject.startsWith("Test");

// Matches messages with a subject starting with "Test"
// or messages that are not read:
Restriction restriction =
    If.Message.Subject.startsWith("Test").or(
    If.Message.IsNotRead );

Date now = new Date();
Date oneDayAgo = new Date(now.getTime() - 86400000);

// Matches items received in the last 24 hours:
Restriction restriction =
    If.Item.DateTimeReceived.isAfterOrEqualTo(oneDayAgo).and().isBefore(now);

// Matches appointments starting AND ending in
// the last 24 hours:
Restriction restriction =
    If.CalendarItem.Start.
        isAfterOrEqualTo(oneDayAgo).and().
        isBefore(now).and(
    If.CalendarItem.End.
        isAfterOrEqualTo(oneDayAgo).and().
        isBefore(now));

Once a Restriction object is created it can be used in the method ItemsCollection.restrict to create a restricted collection of items matching the specified criteria.

The items in a collection can also be sorted by a specific field. The method ItemsCollection.sortBy is used to sort the items. The method accept a value from the ExchangeItemField enumeration.

The following example shows how to apply a Restriction to a collection of items and sort the items by a specific field:

Exchange exchange = new Exchange("hostname","username","password");

// Get the default Calendar folder
ExchangeFolder calendar = exchange.getCalendarFolder();

// Search appointments and sort them by the Start field:
ItemsCollection items = calendar.getItems().
restrict(restriction).sortBy(ExchangeItemField.calendar_Start);

System.out.println("Appointments found: " + items.getCount());

Handling errors

Errors occurring during the communication with the Exchange server are reported by throwing the ExchangeServiceException. Your Java code should catch this exception and handle the error accordingly.

More information

Now you can start building your Java application using our product. For more detailed information, look at:

The JavaDoc: Classes and methods reference

Example source codes

Online documentation