Compoze Software, Inc.

com.compoze.collab.exchange
Interface IExchangeSession

All Superinterfaces:
IGroupwareSession, ISession, java.io.Serializable
All Known Subinterfaces:
IMapiSession, IWebdavSession

public interface IExchangeSession
extends IGroupwareSession

Represents an Exchange session. The following table shows the properties that can be used to open a session:

Property Required Additional Information
PROP_USER_DOMAIN Yes The domain name of the user. This is a windows domain name.
PROP_USER_USERNAME Yes The Windows username to login.
PROP_USER_PASSWORD Yes The user's password.
PROP_EXCHANGE_SERVER See Notes The Exchange server to connect. This can be an IP number or resolvable server name. This can be left blank and automatically determined at runtime. Consult the documention of the specific provider you are using for any additional properties that may need to be set in order for the server to be left blank.

PROP_EXCHANGE_MAILBOX See Notes The mailbox to open. For some providers, this can be left blank and automatically determined at runtim. Otherwise, the PROP_USER_USERNAME property will be used as the mailbox. name. Consult the documention of the specific provider you are using for any additional properties that may need to be set in order for the server to be left blank.

The following table lists properties used if a proxy is required to open a session. If the session is created for the WebDAV provider, these properties will be used to open HTTP/S connections with a proxy server. For the MAPI provider, these are used to connect to a remote service and have the same meaning as when used with WebDAV.

Property Required Additional Information
PROP_PROXY_HOST No The proxy host. This can be an IP number or resolvable server name.
PROP_PROXY_PORT Yes, if host is set. The port to use when connecting to the proxy host.
PROP_PROXY_USERNAME No The username used to authenticate to the proxy server. Not required for all proxy servers.
PROP_PROXY_PASSWORD Yes, if username is set. The password used to authenticate to the proxy server.

An example of using an Exchange session follows

Sample code:

/**
 * The <code>openSession</code> method demonstrates how to open a session with
 * the Exchange provider and use some basic methods in the Exchange package.
 * 
 * @throws  CollaborationException  if the session factory could not instantiate
 *          a session with the given parameters, or if there was an error
 *          retrieving folders, setting properties, or sending a message.
 */
public  void    openSession
(
)
throws  CollaborationException
    {
    Properties p = new Properties ();
    
    // This is one way to specify provider, you can also use the WebDAV provider
    // properties, as detailed in {@link com.compoze.collab.exchange.webdav.IWebdavSession}.
    p.setProperty (IExchangeSession.PROP_PROVIDER, IMapiSession.INTERNAL_NAME);
    p.setProperty (IExchangeSession.PROP_EXCHANGE_SERVER, "server");
    p.setProperty (IExchangeSession.PROP_USER_DOMAIN, "domain");
    p.setProperty (IExchangeSession.PROP_USER_USERNAME, "username");
    p.setProperty (IExchangeSession.PROP_USER_PASSWORD, "password");
    
    // create and open the session
    ISession session = SessionFactory.createSession (p);    
    session.login ();
    
    IRootContainer root = session.getDefaultRootContainer ();
    
    // Get a handle to the inbox.
    IContainer inbox1 = root.getSubcontainer ("Inbox");
    
    // Another way to do the same.
    IContainer inbox2 = ((IGroupwareSession) session).getDefaultContainer (
        DefaultContainerClassEnum.INBOX);
    
    // Get a handle to the outbox, add an item and send it.
    IContainer outbox = root.getSubcontainer ("Outbox");
    IExchangeMessage msg = (IExchangeMessage) outbox.add (IExchangeMessage.CLASS, true);
    msg.addRecipient (RecipientTypeEnum.TO, "user@domain.com");
    msg.setSubject ("Hello From Collab");
    msg.send (true);
    
    session.logout ();
    }

Field Summary
static java.lang.String PROP_EXCHANGE_MAILBOX
          Property name to identify the mailbox to open on the server.
static java.lang.String PROP_EXCHANGE_SERVER
          Property name to identify the exchange server.
static java.lang.String PROP_PROXY_HOST
          Property identifying the proxy host, if required.
static java.lang.String PROP_PROXY_PASSWORD
          Property identifying the proxy password, if required.
static java.lang.String PROP_PROXY_PORT
          Property identifying the proxy port, if required.
static java.lang.String PROP_PROXY_PROTOCOL
          Property identifying the proxy protocol, if required.
static java.lang.String PROP_PROXY_USER
          Property identifying the proxy username, if required.
static java.lang.String PROP_USER_DOMAIN
          Property name to identify the exchange domain.
static java.lang.String PROP_USER_PASSWORD
          Property name to identify the user's password.
static java.lang.String PROP_USER_USERNAME
          Property name to identify the user's username.
 
Fields inherited from interface com.compoze.collab.ISession
PROP_ADMIN_LOCALE, PROP_AUTO_FETCH, PROP_CACHE_DEPENDENCY_CHECK_MILLIS, PROP_CACHE_ENABLED, PROP_CACHE_QUERY_MAX, PROP_CACHE_UPDATE_MILLIS, PROP_CACHE_USE_SOFT_REFERENCES, PROP_LOCALE, PROP_LOG_LEVEL, PROP_PROGRAMMER_LOCALE, PROP_PROVIDER, PROP_SCHEMA, PROPVALUE_REMOVE, STATE_AUTHENTICATED, STATE_INITIALIZED, STATE_OPEN, STATE_UNINITIALIZED
 
Method Summary
 IExchangeAddressEntry getAddressEntry()
          Gets the address entry for the opener of the session.
 IExchangeAddressEntry getAddressEntry(FetchProfile fp)
          Gets the address entry for the opener of the session.
 java.lang.String getAuthorizationValue(java.lang.String sName)
          Gets an authorization token from an Exchange session.
 IExchangeContainer getDefaultContainer(IExchangeAddressEntry entry, DefaultContainerClass type, FetchProfile fp)
          Opens the default container type of another user; if the current session's user has the appropriate permissions.
 void publishFreeBusy()
          Publishes the free/busy data.
 void setAuthorizationValue(java.lang.String sName, java.lang.String sToken)
          Sets an authorization token for the Exchange session to send to the Exchange server.
 
Methods inherited from interface com.compoze.collab.groupware.IGroupwareSession
getCalendar, getDefaultContainer, getDefaultContainer, getRootContainer, getRootContainer, getTimeZone, getTimeZone, setTimeZone
 
Methods inherited from interface com.compoze.collab.ISession
addLogListener, close, endProfile, endTimer, endTimer, getAdminLocale, getAttribute, getDefaultRootContainer, getDefaultRootContainer, getLocale, getLogLevel, getOption, getOptions, getProgrammerLocale, getProperty, getProvider, getState, invalidateCache, isCapabilitySupported, log, login, login, logout, open, open, removeAttribute, setAdminLocale, setAttribute, setLocale, setLogLevel, setOption, setOptions, setProgrammerLocale, startProfile, startProfile, startTimer, startTimer
 

Field Detail

PROP_EXCHANGE_SERVER

public static final java.lang.String PROP_EXCHANGE_SERVER
Property name to identify the exchange server.

PROP_USER_DOMAIN

public static final java.lang.String PROP_USER_DOMAIN
Property name to identify the exchange domain.

PROP_USER_USERNAME

public static final java.lang.String PROP_USER_USERNAME
Property name to identify the user's username.

PROP_USER_PASSWORD

public static final java.lang.String PROP_USER_PASSWORD
Property name to identify the user's password.

PROP_EXCHANGE_MAILBOX

public static final java.lang.String PROP_EXCHANGE_MAILBOX
Property name to identify the mailbox to open on the server.

PROP_PROXY_USER

public static final java.lang.String PROP_PROXY_USER
Property identifying the proxy username, if required.

PROP_PROXY_PASSWORD

public static final java.lang.String PROP_PROXY_PASSWORD
Property identifying the proxy password, if required.

PROP_PROXY_HOST

public static final java.lang.String PROP_PROXY_HOST
Property identifying the proxy host, if required.

PROP_PROXY_PORT

public static final java.lang.String PROP_PROXY_PORT
Property identifying the proxy port, if required.

PROP_PROXY_PROTOCOL

public static final java.lang.String PROP_PROXY_PROTOCOL
Property identifying the proxy protocol, if required.
Method Detail

publishFreeBusy

public void publishFreeBusy()
                     throws CollaborationException
Publishes the free/busy data.
Throws:
CollaborationException - if there was an error reading or writing free/busy information

getAddressEntry

public IExchangeAddressEntry getAddressEntry()
                                      throws CollaborationException
Gets the address entry for the opener of the session. This method uses a fetch profile consisting of the default keys for an IExchangeAddressEntry.
Returns:
the address entry
Throws:
CollaborationException - if there was an error getting the address entry

getAddressEntry

public IExchangeAddressEntry getAddressEntry(FetchProfile fp)
                                      throws CollaborationException
Gets the address entry for the opener of the session.
Parameters:
fp - the fetch profile to use when getting the address entry
Returns:
the address entry
Throws:
CollaborationException - if there was an error getting the address entry

getDefaultContainer

public IExchangeContainer getDefaultContainer(IExchangeAddressEntry entry,
                                              DefaultContainerClass type,
                                              FetchProfile fp)
                                       throws CollaborationException
Opens the default container type of another user; if the current session's user has the appropriate permissions. The keys listed in the See Also section are required on the specified address entry.
Parameters:
entry - the address entry of the user to open. Requires the keys defined in the See Also section.
type - the default container class to open.
fp - the fetch profile to use when opening the container
Returns:
the container
Throws:
CollaborationException - if there was an error opening the container
See Also:
IExchangeAddressEntry.ALIAS

setAuthorizationValue

public void setAuthorizationValue(java.lang.String sName,
                                  java.lang.String sToken)
Sets an authorization token for the Exchange session to send to the Exchange server. The authorization token is used as a method of authentication against Exchange instead of the traditionaly username, password and domain combination.
Parameters:
sName - the name of the authorization token to set.
sToken - the authorization token value

getAuthorizationValue

public java.lang.String getAuthorizationValue(java.lang.String sName)
Gets an authorization token from an Exchange session. The authentication token is not guaranteed to match the original token that was set on the session. If the server instructs the Exchange session to update its token, it will automatically maintain the latest token in the chain.
Parameters:
sName - the name of the authorization token to get (not null).
Returns:
the latest authentication token, or null if the token value for the given name could not be found.

Compoze Software, Inc.

Copyright ©1999-2005 Compoze Software, Inc. All rights reserved.