Introduction
JEC/EWSJ provides a java connector to exchange
server. With it you can write java code that accesses
and manipulates calendar, contacts, tasks, emails,
send meeting requests and accept meeting requests
in exchange server. Basically JEC and EWSJ have
the same feature set, the difference is that JEC
uses the WebDAV interface and EWSJ uses the Web
Services interface, which makes the last more suitable
to exchange 2007 server. In case you have both WebDav
and EWS interfaces open, you'll need to evaluate
both products to see which one is better suited
to your needs. Our recommendation is to use EWSJ
for 2007 and JEC for 2000 and 2003.
Here are some basic Examples, for the full examples
look at ExchangeConnectorExamples.java and EWSJExamples.java
in the example directory of the evaluation download.
Basic Connection
JEC Basic Connection
Expand jec distribution to a file system location
without spaces.
The JEC library is the jar jec.jar, so include
it in your classpath before you try the following
code examples and explanations.
Please
include as well the library 'lib' that is included in JEC package in
order to include your license, otherwise JEC will throw an invalid
license exception.
In order to connect to an exchange server you first need to know the domain name or the ip of the exchange server.
You will need to know as well a username and
a password by which you want to connect to the
exchange server, just as when you connect with
a regular outlook client to an exchange server
you provide a username and a password; when you
connect with the connect you actually connect
with a certain username, to a specific mailbox,
So for the sake of the example we'll use "some_username"
as a username and "some_password" as a password.
In most cases the username and the mailbox name
are the same, in rare cases they are not the same,
to find out your mailbox name, look at
this user-guide.
The third thing to know when connecting to an
exchange server is the prefix of the exchange
server, by default its "Exchange".
You also need to know if you server use SSL connection,
if it is set the boolean parameter to true if
not false.
The command to perform that connection is then:
ExchangeConnectorFactory
factory = new ExchangeConnectorFactory();
ExchangeConnectorInterface connector = null;
connector = factory.createExchangeConnector("exchange
ip or host name", "some_username", "some_password",
"prefix usually its 'Exchange'","use SSL:
true/false", "mail box name for user user1
this would be usually 'user1'");
Then you want to retreive a list of contacts, you perform that by:
List contacts = connector.getContacts();
EWSJ Basic Connection
Expand EWSJ distribution to a file system location
without spaces. Include ewsj.jar (in the
bin directory) and all the jars in the lib directory
in the CLASSPATH, you should also include the
lib directory itself in the CLASSPATH (this enables
EWSJ find the license file and more configuration
files).
To successful connect to Exchange via the EWS
interface you will need to know this parameters:
1. Username: your Exchange username.
2. Password: your Exchange password.
3. AccountName: The account you want to
connect to (in most cases its the same as your
user name, except in case of impersonation or
mailbox sharing, see related user-guide).
4. Domain: your domain name.
5. useSSL: Boolean that indicates if you
use secure connection.
6. Prefix: Always "Exchange".
You can test if your Exchange EWS interface is
open via this URL:
http(s)://<exchange_host>/ews/Exchange.asmx
If you get a valid response (xml response), then
its OK you have EWS Interface open, if not, contact
your Exchange Administrator to open the EWS interface.
After you have the above information you can connect to Exchange using this lines of code:
EWSConnectorFactory factory = new EWSConnectorFactory();
EWSConnectorInterface connector = null;
connector = factory.createEWSConnector(_exchangeHost,
_userName,
_password,
_prefix, _useSSL, _accountName);
ArrayList contacts = connector.getContacts();
If you still have problems to connect to Exchange,
please see:
EWSJ Connection problems
User-Guide.
You can quickly create EWSJ eclipse project using this user guide:
Define EWSJ Examples Eclipse project
Examples
List Contacts
The following example present how to access and retrieve
contacts with JExchangeConnector
ExchangeConnectorFactory
factory = new ExchangeConnectorFactory();
ExchangeConnectorInterface connector = null;
connector = factory.createExchangeConnector("exchange
ip or host name", "some_username", "some_password",
"prefix usually its 'Exchange'", "mail box name
for user user1 this would be usually 'user1'");
List
contacts = connector.getContacts();
for (int i = 0; i < contacts.size();
i++) {
ExchangeContact contact = (ExchangeContact)
cntacts.get(i);
List Calendar Events
With the connector's listEvents(...) method which
is very similar to getContacts(...) you can get
a list of events starting on a certain start date
time and ending on another date time. If you want
to retrieve a list of calendar events all you
need to do is to create a connection as explained
in the "Basic Connection" section which is stated
above, and using this connection call the method
getEvents(...).
So the steps are, first create a connection, then create two date objects that contain the start datetime and the end datetime
SimpleDateFormat
dateFormat = new SimpleDateFormat("yyyy-MM-dd
HH:mm:ss");
Date startDate
= dateFormat.parse("2006-11-24 08:00:00");
Date endDate = dateFormat.parse("2006-11-24 21:00:00");
Then call the getEvents(...) method of the connection that accepts 3 parameters:
- Start Date Time - (java.util.Date) The start date time where you want the events to be retreived to be taken from
- End Date Time - (java.util.Date) Events will be retreived not after this date time.
- Maximum number of rows to be retreived.
The return value of listEvents(...) method is an
ArrayList of ExchangeEventDTO, using this arrayList
and each ExchangeEventDTO item you can print the
details of each calendar event in the following
manner:
So the code to get the events would look like this:
ArrayList
events = connector.getEvents(startDate, endDate,
5);
for(int i = 0; i < events.size(); i++) {
System.out.println("event " + i + " subject: " +
((ExchangeEventDTO) events.get(i)).getSubject();
System.out.println("event"
+ i + " location: " + ((ExchangeEventDTO) events.get(i)).getLocation();
} // End of for loop
You can tell JEC to bring all your calendar events
with within a date range:
public
ArrayList getEvents(Date startDate, Date endDate,
int maxRows) throws ExchangeGeneralException
Or you can tell JEC to bring only a subset of your
calendar events based on a EventSearchCriteria class.
public
ArrayList getEvents(Date startDate, Date endDate,
EventSearchCriteria eventSearchCriteria ) throws
ExchangeGeneralException;
EventSearchCriteria contains and thus filters by the following fields:Subject [regexp filter]
* Location [regexp filter]
* Description [regexp filter]
* Is recurrent [-1, 0, 1]
* Is all day event [-1, 0, 1]
For the first three items (subject, location, description) you can
search with a regular expression filter, that means that if you filter
by '.*' subject you are actually giving no limit on the subject header,
if you search by '.*Jack.*' you will receive all meetings that contain
Jack in the subject.
For the Is recurrent and all day event filters the filters goes like this:
* -1 - No filter, doesn't matter the value of the
field it will be returned.
* 0 - Result will be returned only if the value of the field is false.
* 1 - Result will be returned only if the value of the field is true.
Examples:
Bring all events from startDate to endDate doesn't
matter what the subject, location, description is
where the event are recurrent and doesn't matter
if the event is an all day event:
get all events that their subject contains the word
"the" no case sensitive
EventSearchCriteria
eventSearchCriteria = new EventSearchCriteria(".*",
".*", ".*", 1, -1);
List events = connector.getEvents(startDate, endDate,
eventSearchCriteria);
get all events that their subject contains the word "the" no case sensitive
EventSearchCriteria
eventSearchCriteria = new EventSearchCriteria(
".*[tT][Hh][Ee].*", ".*", ".*", -1, -1);
get all events that their subject contains the word "the"
EventSearchCriteria
eventSearchCriteria = new EventSearchCriteria(
".*the.*", ".*", ".*", -1, -1);
FBA Authentication
To connect to exchange server with FBA (Forms Based
Authentication) you connect as usual with 2 differences,
1. you have to set the domain name. 2. you need
to set useFBA to true. Here is a code snippet (for
the full example look at getEmailsWithFBAExample()
):
connector = factory.createExchangeConnector(_exchangeHost,
_applicationUserAccountName,
_applicationUserPassword,
_prefix, useSSL, _mailboxName);
connector.setDomain("YourDomain.com");
connector.setUseFba(true);
ArrayList emailsArrayList = connector.getEmails(
null,
null,
null,
maxEmailsReturned);
FBA need to be set in case you get Error 440 from the exchange server when trying to connect using JEC.
NTLM (Windows Integrated)
Authentication To connect to exchange server
with NTLM you connect as usual with 2 differences,
1. you have to set the domain name. 2. you need
to set useNTLM to true. Here is a code snippet (for
the full example look at getEventWithNTLMAuthnticationExample()
):
connector.setDomain("YourDomain.com");
connector.setUseNTLMAuthentication(true); ArrayList events = connector.getEvents(startDate,
endDate, 5);
Send Email with attachment
Here is a code snippet, for full example look at sendEmailWithAttachmentsExample():
cconnector.setDraftsFolderName("drafts");
ExchangeEmailDTO email = new ExchangeEmailDTO();
String emailUniqueId = "" + System.currentTimeMillis();
email.setUniqueIdForUrl(emailUniqueId);
email.setSubject("test email for send");
email.setBody("test body for send");
AttachmentDTO attachment1 = new AttachmentDTO();
attachment1.setName("authentication_matrix.txt");
attachment1.setPath("./doc/authentication_matrix.txt");
email.AddAttachemt(attachment1);
AttachmentDTO attachment2 = new AttachmentDTO();
attachment2.setName("authentication_matrix1.txt");
attachment2.setPath("./doc/authentication_matrix.txt");
email.AddAttachemt(attachment2);
email.setFrom(emailfrom);
email.setTo("test2@domain1.com");
email.setCc("test3@domain1.com");
connector.sendEmail(email);
Get Folders
Here is a code snippet, for full example look at getFoldersExample():
connector = factory.createExchangeConnector(_exchangeHost,
_applicationUserAccountName,
_applicationUserPassword,
_prefix, _useSSL, _mailboxName);
ArrayList folders = connector.getRootFolders();
String folderUrl = null;
String folderName = null;
String subFolderUrl = null;
for (int i = 0; i < folders.size(); i++) {
folderUrl = ((FolderDTO)folders.get(i)).getUrl();
folderName = ((FolderDTO)folders.get(i)).getName();
System.out.println("folder Url: " + folderUrl );
System.out.println("folder name: " + folderName );
ArrayList subFolders = null;
// getting the folders of
the subfolder "emails test"
if (folderName.equals("emails_test"))
{
subFolders = connector.getFolders(folderUrl);
for (int j = 0; j < subFolders.size(); j++) {
subFolderUrl = ((FolderDTO)subFolders.get(j)).getUrl();
System.out.println("subfolder Url: " +
subFolderUrl );
}
}
}
Run the Advanced examples
To run the Advanced examples (in JEC advanced_examples folder) you should add the optional package to JEC lib directory.
download from:
optional package
|