10
Calendar Web Services Client-Side Java Implementation

This chapter describes the design of the set of Java classes used to provide contextual collaboration through the access of calendaring data via Oracle Calendar web services. These "Calendarlet" classes attempt to hide the many details of using web services technology in a Java environment.

The class implementation does not attempt to provide all the iCalendar properties and attributes, but is focused on the elements supported in the V2 implementation of the Oracle Calendar web services toolkit.

Note:

You can find JavaDoc information and TestTool samples in the Oracle Calendar web services toolkit.

Java Classes

There are a few general steps to follow when using the Calendarlet classes:

Initialize your authentication mechanism.
Initialize your Query, including data type.
Bind the authentication and query object to a Calendarlet instance.
Set the target URL in the Calendarlet instance.
Make the SOAP call.
Parse the results.

The Calendarlet class implementation relies heavily on Apache SOAP classes to perform most of the protocol level handling. For incoming and outgoing messages, these same Apache SOAP classes are used, along with W3C DOM classes. To generate outgoing messages, Calendarlet and iCalendar classes are instantiated and set on parent classes. To generate the final XML stream, all classes implement a getElement() method. This is intended to build an XML DOM representation of the SOAP message to be transmitted. The lower level Apache SOAP calls require this DOM structure to obtain the final stream.

For incoming messages, the Calendarlet and iCalendar classes are reconstructed through the unmarshall() static method on each class, again using the XML DOM received from the lower level Apache SOAP classes. This unmarshalling of the DOM consists of the parent class recognizing a child tag and invoking that child's class unmarshall() method.

If for any reason there is an XML parsing error, a low level Apache SOAP exception is thrown; the Calendarlet classes will never get a chance to parse the data. If there is a contextual error, meaning the XML is valid but elements are in the wrong place or not recognized, a Calendarlet exception will be thrown.

Ideally, all incoming xCal (the XML binding of iCalendar) can have extended elements within the data. However, for this implementation, extended elements will only be handled at the vEvent level.

The Calendarlet class provides some debugging support. There are two main features:

The ability to capture the input and output buffers; the method setWantIOBuffers() must be called before invoking a SOAP method (not recommended for a final deployment). Both the input and output buffers are captured and stored in the CalendaringResponse class.
The ability to get the total processing time (in milliseconds) of the SOAP request, also stored within the CalendarletResponse.

Fetching Data

Using the Java Calendarlet classes, the following code could be used to generate the SOAP request:

     // initialize the authentication information
     // and set the user id
     BasicAuth auth = new BasicAuth();

     auth.setName("*** userid ***");
     auth.setPassword("*** password ***");

     // initialize the event search command and query
     SearchCommand search = new SearchCommand();

     search.setCmdId("my cmd id 1");

     // create a query to retrieve unconfirmed events
     vQuery            query       = new vQuery();
     query.setFrom(vQuery.k_queryFromEvent);

     // determine the datestamps for a weeks worth of events

     // use the CalendarUtils to get a proper timestamp with
     // time zone information set properly
     Calendar today = CalendarUtils.getToday();

     int dayOfWeek = today.get(Calendar.DAY_OF_WEEK);
            
     Calendar beginWeek = (Calendar)today.clone();
     Calendar endWeek   = (Calendar)today.clone();
            
     beginWeek.add(Calendar.DATE, 1 - dayOfWeek);
     endWeek.add(Calendar.DATE, 8 - dayOfWeek);
     endWeek.add(Calendar.MINUTE, -1);

     // use the CalendarUtils to help generate a date range query
     query.setWhere(CalendarUtils.getDateRangeQuery(beginWeek, endWeek));
            
     search.setQuery(query);
            
     // create the calendar client SOAP stub
     // and set the basic authentication header
     Calendarlet cws = new Calendarlet();

     // set the Web Services host URL
     cws.setEndPointURL("http://www.thehost.com");

     cws.setAuthenticationHeader(auth.getElement());

     // make the SOAP call
     CalendaringResponse response = cws.Search(search.getElement());

The resulting response contains iCalendar objects, with the requested properties returned. Using the Calendarlet Java classes, the iCalendars can be traversed to find the vEvents.

     // get the SOAP reply
     Reply reply = (Reply)response.getCalendarReply();

     // traverse all the iCalendar objects
     Vector someiCalendars =  iCalendar.unmarshallVector(
                                                    reply.getEntries());
     int    numiCalendars  = someiCalendars.size();

     for (int i = 0;  i < numiCalendars; i++)
     {
          iCalendar iCalObj = (iCalendar)someiCalendars.get(i);

          // traverse all the vCalendar objects
          Vector somevCalendars = iCalObj.getvCalendars();
          int    numvCalendars  = somevCalendars.size();

          for (int j = 0;  j < numvCalendars;  j++)
          {
               vCalendar vCalObj = (vCalendar)somevCalendars.get(j);

               // traverse all the vEvent objects
               Vector somevEvents = vCalObj.getComponents();
               int    numvEvents  = somevEvents.size();

               for (int k = 0;  k < numvEvents;  k++)
               {
                    vEvent vEventObj = (vEvent)somevEvents.get(i);

                    // get the specific properties
                    String title     = vEventObj.getSummary();
                    String dtstart   = vEventObj.getDtStart();
                    String dtend     = vEventObj.getDtEnd();
                    String eventType = vEventObj.getXEventType();

                    // do something interesting with the meeting info
               }
          }
     }

Soap Faults and Exceptions

There are two types of errors that can occur with the web services toolkit: A Java exception or a SOAP fault.

The Java Exception originates from the Calendarlet class, the underlying Apache SOAP or W3C DOM classes, or the Java Runtime. For each SOAP method that is invoked on the Calendarlet class, an exception may be thrown as a result of some internal processing error or an XML parsing problem. These are typically client-side unexpected errors that must be properly handled.

The SOAP Fault is the result of an error from the Oracle Calendar web service (that is, a remote server-side error). Whenever a server-side error occurs, the web service returns a SOAP Fault as the response to the HTTP transaction. There is no Java-based exception thrown. Within a SOAP Fault, the details field may contain an Oracle Calendar web services Error object, with an important error code. For a list of error codes, see Chapter 11, "Calendar Web Services Status Codes".

A CalendarUtils method can help determine whether a SOAP fault has occurred and retrieve the web services error.

     // Calendar response 
     CalendaringResponse response = cws.Search(...);

     // get the vector of entries embedded
     // in the SOAP body
     Vector bodyEntries = response.getBodyEntries();

     // determine if there was a SOAP Fault
     if (!CalendarUtils.isSOAPFault(bodyEntries))
     {
          // do regular processing
     }
     else
     {
          // get the SOAP fault object
          org.apache.soap.Fault soapFault = 
                    CalendarUtils.getSOAPFault(bodyEntries);

          // get the calendar Web Services error
          Error calendaringError = Error.unmarshall(soapFault);

          // get the Web Services error code
          String errorCode = calendaringError.getCode();
     }

Local Time

There are two important date formats to be aware of: Date and DateTime. The DateTime format contains both date and time information within the string, while Date contains only time information. DateTime is generally used for regular meetings, while Date is used for Day Events, Daily Notes, and Holidays.

To help generate UTC datetime strings for a vQuery, the CalendarUtils will have a class to take a standard Java Calendar class object and generate a proper string of the form "yyyyMMddThhmmssZ". Java's Calendar class can have a Java time zone associated with it. It is up to the user of the Calendarlet classes to determine the proper time zone and set it in the Java Calendar class.

     // set the date through some mechanism
     // ensure the proper time zone is set
     TimeZone localTimezone = TimeZone.getDefault();
     Calendar theDate       = Calendar.getInstance(localTimezone);

     String utcString = CalendarUtils.getUTCDateTime(theDate);

To help generate UTC date strings for a vQuery, the CalendarUtils will have a class to take a standard Java Calendar class object and generate a proper string of the form "yyyyMMdd". Java's Calendar class can have a Java time zone associated with it. It is up to the user of the Calendarlet classes to determine the proper time zone and set it in the Java Calendar class.

     // set the date through some mechanism
     // ensure the proper time zone is set
     TimeZone localTimezone = TimeZone.getDefault();
     Calendar theDate       = Calendar.getInstance(localTimezone);

     String utcString = CalendarUtils.getUTCDate(theDate);

Since many calendaring query operations are relative to today's date, an additional CalendarUtils method is provided to help base vQuery datetime stamps. The method will return a datetime stamp of midnight today, local time and will be of the form "yyyyMMddTxxxx00Z", where xxxx is the hour and minute offset from UTC (note some time zones are half-hour offsets).

     String utcToday = CalendarUtils.getToday();

Typical calendar server query time ranges are from local midnight of a specific date to one minute before midnight of the day before the last date. For example, if today is June 01, 2003 in EST time, the getToday() method will return 20030602T040000Z. For a day date range, the end date would be 20030603T035900Z.

10 Calendar Web Services Client-Side Java Implementation

Java Classes

Fetching Data

Soap Faults and Exceptions

Local Time

10
Calendar Web Services Client-Side Java Implementation