Sun Identity Manager Deployment Guide

How to Write Active Sync-Enabled Adapter Methods

Active Sync-specific methods provide the mechanism for updating Identity Manager, which is the primary purpose of your Active Sync-enabled adapter adapter. These methods are based on pulling information from the authoritative resource. In addition, you use these methods to start, stop, and schedule the adapter.

The methods you are going to write in this section of the adapter are based on generic methods supplied with the skeleton adapter file. You must edit some of these methods, which are categorized by task.

The following sections describe general guidelines for creating Active Sync-enabled adapter methods:

Initializing and Scheduling the Adapter

You initialize and schedule the adapter by implementing the init() and poll() methods.

The init() method is called when the adapter manager loads the adapter. There are two methods for loading the adapter:

In the initialization process, the adapter can perform its own initialization. Typically, this involves initializing logging (with the ActiveSyncUtil class), and any adapter-specific initialization such as registering with a resource to receive update events.

If an exception is thrown, the adapter is shut down and unloaded.

Polling the Resource

All of the adapter’s work is performed by the poll() method. Scheduling the adapter requires setting up a poll() method to search for and retrieve changed information on the resource.

This method is the main method of the Active Sync-enabled adapter. The adapter manager calls the poll() method to poll the remote resource for changes. The call then converts the changes into IAPI calls and posts them back to a server. This method is called on its own thread and can block for as long as needed.

It should call its ActiveSyncUtil instance’s isStopRequested method and return when true. Check isStopRequested as part of the loop condition when looping through changes.

To configure defaults for polling, you can set the polling-related resource attributes in the adapter file. Setting these polling-related attributes provides administrators with a means to later use the Identity Manager interface to set the start time and date for the poll interval and the length of the interval.

Scheduling Parameters

You use the following scheduling parameters in Active Sync-enabled adapters:

See Table 9–6 for a description of these parameters.

Scheduling Parameters in the prototypeXML

The scheduling parameters are present in the string constant ActiveSync. ACTIVE_SYNC_STD_RES_ATTRS_XML, along with all other general Active Sync-related resource attributes.

The following table describes the usage of scheduling parameters using some sample polling scenarios.

Table 9–26 Sample Polling Scenarios

Polling Scenario  

Parameters  

Daily at 2 A.M. 

Interval = day, count =1, start_time=0200

Four times daily 

Interval=hour, count=6.

Poll once every two weeks on Thursday at 5 P.M 

Interval = week, count=2, start date = 20020705 (a Thursday), time = 17:00.

Storing and Retrieving Adapter Attributes

Most Active Sync-enabled adapters are also standard adapters, where a single Java class both extends ResourceAdapterBase (or AgentResourceAdapter) and implements the Active Sync interface.

The following example shows how to retrieve the attribute and pass the update through to the base.


Example 9–5 Attribute Retrieval and Update


public Object getAttributeValue(String name) throws WavesetException {
return getResource().getResourceAttributeVal(name); }
public void setAttributeValue(String name, Object value) throws WavesetException {
getResource().setResourceAttributeVal(name,value);

Updating the Identity Manager Repository

When an update is received, the adapter uses the IAPI classes, notably IAPIFactory to:

Mapping the Changes to the Identity Manager Object

Using the Active Sync event parameter configurator for the resource, IAPIFactory.getIAPI constructs an IAPI object, either IAPIUser or IAPIProcess from a map of changed attributes. If an exclusion rule (iapi_create, iapi_delete, or iapi_update) is configured for the resource, IAPIFactory checks if the account is excluded. If a non-null object is created and returned by the Factory, the adapter can modify the IAPI object (for example, by adding a logger), then submits it.

When the object is submitted, the form associated with the resource is expanded with the object view before the view is checked in. For more information about forms and views, see Deployment Reference.

In SkeletonActiveSyncResourceAdapter, this process is handled in the buildEvent and processUpdates methods.

Shutting Down the Adapter

No system requirements are associated with adapter shutdown. Identity Manager calls the shutdown method, which is an opportunity for your adapter to cleanup any objects still in use from the polling loop.