Moyosoft Products | Services | Download | Contact us    
Java Bridge to Exchange
Products  >  Java Bridge to Exchange  >  Getting started    
Getting started
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:

FolderReturned by method
Root folderExchange.getRootFolder
      Freebusy Data
      Reminders
      Schedule
      To-Do Search
      Top of Information StoreExchange.getTopFolder
            CalendarExchange.getCalendarFolder
            ContactsExchange.getContactsFolder
            Drafts 
            InboxExchange.getInboxFolder
            Sent ItemsExchange.getSentItemsFolder
            TasksExchange.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 = (ExchangeContactitem;
    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: