|
| |
| Sun Java System Calendar Server 6 2005Q1 Developer's Guide | |
Chapter 1
Calendar Server API (CSAPI) OverviewThis chapter gives an overview of the Calendar Server API (CSAPI), a set of high performance programmatic interfaces that enables you to modify or enhance the feature set of Sun Java™ System Calendar Server 6 2005Q1 (Calendar Server), formerly Sun™ ONE Calendar Server. CSAPI allows you to create very fast runtime shared objects that outperform both system executables and scripts in any language, with respect to speed, memory footprint, and load. All of these factors contribute to scalability issues in high-end systems.
This chapter has the following sections:
CSAPI ArchitectureThe CSAPI is a group of shared-object runtime interfaces to Calendar Server functions. You can use plug-in CSAPI modules to manipulate server data for incoming requests and for responses. This architecture allows the server to act as a simple gateway to data it knows nothing about. It also allows for dynamic logging and statistics tracking, external authentication schemes, user attribute manipulation, and a variety of other functions.
Figure 1-1, which follows, shows the relationship of CSAPI modules to other subsystems within Calendar Server. Depending on which functional group or groups a CSAPI module supports, it can interact with one or more areas of Calendar Server functionality, such as data formatting, authentication, and directory services.
A module is a shared object (.so file) on Unix, or dynamic linked library (.dll file) on Windows NT. Each module that you provide implements one or more of the CSAPI interfaces (or pure virtual base classes) defined in this document; see Chapter 2, "CSAPI Reference." Each client-side interface addresses a functional area of Calendar Server. The implementation contained in a module can either augment or override the native Calendar Server functionality in its area.
A set of server-side APIs allows CSAPI modules to get the server’s version information, and use the server’s fast memory allocation mechanism.
The installation contains plug-ins for each of the CSAPI interfaces with the default code, which you can use as templates to create your own plug-ins, along with all supporting libraries and headers.
Figure 1-1 CSAPI Relationship to Other Subsystems
Thread Safe Requirement
CSAPI module plug-ins must be thread safe, as many thousands of threads can access a module at any time. For those plug-ins that cannot be thread-aware, use simple monitors at the function-call level in the plug-in itself. For more information on Netscape™ Portable Runtime (NSPR) threads, refer to the NSPR reference manual at mozilla.org. For the URL, see the Dependencies section later in this chapter.
Dependencies
CSAPI is a C and C++ interface for Unix and Windows NT systems. It uses Netscape Portable Runtime (NSPR), a part of the mozilla.org source code that is a platform independent API to operating system services, and XPCOM for Interface Dispatch.
For documentation on NSPR see the Mozilla™ technical documentation site:
http://www.mozilla.org/projects/nspr/reference/html/index.html
For documentation on XPCOM, see:
http://www.mozilla.org/projects/xpcom
You must use NSPR for platform-independent C data types and runtime functions in implementations that need to run on different platforms. Calendar Server uses the XPCOM C++ API (QueryInterface) to discover the exact interfaces a specific module implements.
Using CSAPIThe following section describes how the system loads and uses the plug-ins you provide. Default plug-ins ship with the system. You may choose to augment or override any or all of them.
Loading CSAPI Modules
Calendar Server loads CSAPI modules from the cal/bin/plugins directory at startup and unloads them at server shutdown. All plug-in modules must reside in this directory and have filenames that are prefaced with cs_.
The server checks ics.conf for the modules to be dynamically loaded at server startup. If the value of the preference csapi.plugin.loadall is y, the server loads all shared objects in the cal/bin/plugins directory whose names begin with the prefix cs_. Otherwise, if the value is n, various parameters exist for the various plug-ins. For more information on the preferences in ics.conf, see the Calendar Server Administration Guide.
To specify the loading of a specific plug-in, csapi.plugin.loadall must be set to n. In addition, two parameters must be used: csapi.plugin.plugin name, with a value of y, and csapi.plugin.plugin name.name, with the value being the name of the plug-in.
For example, to load only the calendar-lookup plug-in, the parameters are:
csapi.plugin.loadall = "n"
csapi.plugin.calendarlookup = "y"
csapi.plugin.calendarlookup.name = "calendarlookup"
Note that the plugin name part of the parameter must match on both parameters, but that it does not have to be the same as the value of the .name parameter. Thus, if you wanted to create a plug-in called cs_myown_plugin, you could call the parameters csapi.plugin.anyname, and csapi.plugin.anyname.name. The value of csapi.plugin.anyname.name must be “cs_myown_plugin”.
Calendar Server uses the NSPR function PR_LoadLibrary() to load the shared object at startup, the function PR_UnloadLibrary to unload the shared image at shutdown. Once a shared object is loaded into memory, Calendar Server uses the function PR_FindSymbol to find entry points to known API implementations.
Plug-in Interfaces
All CSAPI plug-ins support one and only one exported symbol, NSGetFactory, as required by the XPCOM specification. From this entry point, Calendar Server calls the XPCOM method QueryInterface to find an object implementing the csIPlugin interface. This allows the server to query the plug-in for version, description, and vendor information. This interface is optional; however, it is highly recommended that you implement it so the server can ensure version control.
Plug-in Version Numbers
Each default plug-in interface can have a different version number. Version numbers increment by a whole number when the API is updated by Sun Microsystems, Inc. All custom plug-ins must use the methods in the current version of the default plug-in API.
If you created a custom plug-in based on an earlier default plug-in version, you must update your custom plug-in to use the new version of all updated methods, and you must increment its version number to reflect the current version number of the default plug-in.
The system will not load plug-ins with version numbers below the current default version number. Your plug-in must have a version number greater than the current default plug-in, but less than the next whole number. For example, if you are writing, or have created in the past, a custom plug-in for csIDatabaseLookup, which is currently at version 2.0, your plug-in version number must be greater than 2.0 and less than 3.0.
Table 1-1 lists the current version of each plug-in API.
Client and Server APIs
The CSAPIs fall into two categories, client and server APIs.
Table 1-2 lists the CSAPI client interfaces, which may be implemented by one or more plug-ins.
The interfaces are described in detail in Chapter 2, "CSAPI Reference."
All interfaces have the following initialization method that you must implement:
Init (nsISupports * aServer);
The server invokes this method immediately after it registers the interface in a newly loaded module. In the module, you can bind the parameter that the server returns, aServer, and use it to refer to the server instance. Your custom plug-in can use the QueryInterface method to find the server interfaces, listed in Table 1-3:
Table 1-3 CSAPI Server APIs
Server Interface
Description
Provides general server information, including version number.
Allows access to server’s memory allocation mechanism.
Server Query Example
The following example checks the version of Calendar Server. It demonstrates how to do the following:
- Bind the returned reference from the Init method.
- Query the server for an interface.
- Call a server method in that interface.
- Release the server reference.
NS_IMETHODIMP csDataTranslator :: Init(nsISupports * aServer)
{
nsresult res = NS_COMFALSE ;
PRUint32 min, maj;
csICalendarServer * cs;
/* QueryInterface for CalendarServer. If call succeeds, server
increments reference count */
if (aServer)
res = aServer->QueryInterface(kICalendarServerIID,(void**)&cs);
/* If succeeded in getting reference to server, check version */
if (NS_SUCCEEDED(res)) {
cs->GetVersion(maj,min);
if (min > 0 && maj >= 1)
res = NS_OK;
else
res = NS_COMFALSE;
/* Release this reference to the server instance */
cs->Release();
}
return res;
}
CSAPI SamplesThe distribution includes sample code for three of the CSAPI interfaces in the csapi/samples directory. You can use these files as templates in building your own CSAPI modules.
The following sample modules are provided:
