Calendar-WS: Programming Notes

This document offers brief programming notes for accessing Calendar-WS, a Web Services interface to CalAgenda, the shared calendaring system on the University of California, Berkeley campus.

With relatively few lines of code, your campus or departmental application can find, add, and delete events on CalAgenda calendars for people, roles, resources, and events. Your application can access any calendar to which it has designate or direct access.

You can do this via Web Services, which is simply a standardized way of sending messages between pieces of software. To make your task easier, you can use a Web Services toolkit, which takes care of many of the underlying message- and transport-related details, allowing you to write clean and simple, high-level code. Web Services toolkits are available for many different programming and scripting languages, and run on every popular type of computing platform; many are free and open source.

Here are some suggested steps for getting started:

1. Find a Web Services toolkit for your programming language or environment.
   
   You can find an extensive list of such toolkits for many different programming and scripting languages in this resources list, maintained by the authors of an open source Web Services toolkit for Perl:

   SOAP::Lite - Resources - SOAP Toolkits

2. Set up your Web Services toolkit so that it can securely access the Calendar-WS service using HTTP over SSL (e.g. so it can connect to https:// URLs).
   
   Under some circumstances, this may require special configuration and/or the addition of extra software pieces.
   
   Examples:
   • SOAP::Lite for Perl requires the installation of the Crypt::SSLeay module.
     (Installation of this module is also offered as an option during the installation of SOAP::Lite.)
   • nuSOAP and the Pear SOAP package for PHP appear to both require installation of the CURL package and compilation of PHP for CURL support.
   • SOAP toolkits for Java require JSSE, which is included with Java 1.4 and higher and can optionally be installed under Java 1.2 and 1.3.
     
     Note: Java toolkits which connect to certain test instances of the Calendar-WS interface that may use self-signed digital certificates will likely also need to locally install a copy of the server's public key, using the keytool utility, and reference the keystore in which that public key has been installed via a Java system property.
3. In your Web Services client code, specify that you'll be connecting to the Calendar-WS service at either:
   
   The WSDL description of the service:
   https://calendar-ws.berkeley.edu:8004/calendaraccess/services/CalendarAccessImpl.wsdl
   
   or
   
   The implementation class for the service:
   https://calendar-ws.berkeley.edu:8004/calendaraccess/services/CalendarAccessImpl
   
   
   The choice of which URL to use will depend on the specific requirements of your Web Services toolkit, as described in its documentation.
   
   The WSDL description (choice 1, above) points to the URL of the implementation class (choice 2), so whichever mechanism your Web Services toolkit uses, it will ultimately end up invoking the same code.
   If you wish to connect to a test server to test your application against future changes in the Calendar-WS interface, substitute
   
   calendar-ws-test.berkeley.edu:8004
   
   for the hostname and port in either of the URLs above.
4. Write Web Services client code to access the pingServer remote procedure.
   
   This procedure does not require any authentication, and is a good way to test that the basics are working: that your SOAP toolkit is correctly installed and its SSL support enabled, and that your code is successfully connecting to the Calendar-WS service.
   
   (Calling this procedure will also verify that the Calendar-WS service is operational and can connect to its calendar server at the back end.)
   
   There is a detailed description of how to call this procedure in the Calendar-WS Web Services interface document.
   Sample code is also available for your reference.
5. Write Web Services client code to access the other procedures offered by the Calendar-WS service:
   
   GetEventsByRange
   GetEvent
   AddEvent
   DeleteEvent
   
   You can authenticate to the service, as well as testing designate access, by using a set of test accounts which are available to all developers. You can also request that new user and resource accounts be set up for your exclusive use on the test server.
   
   There are detailed descriptions of how to call these procedures in the Calendar-WS Web Services interface document.
   
   Sample code demonstrating how to call these procedures is also available for your reference.
6. Write code to process the results returned by these procedures.
   
   The XML-based format of the results is described in the Results Returned section of the Web Services interface documentation. This description is currently by way of examples; schema for the results format will be provided at a later time.
   
   Sample code demonstrating how to parse the results is also available for your reference.
7. Debug any errors in your code.
   
   Here is a list of some common error messages your application may encounter, including suggestions for how to resolve the errors.
8. Write code to integrate your interactions with the Calendar-WS interface with your new or existing application.