Oracle Calendar Application Developer's Guide Release 2 (9.0.4) Part Number B10893-01 |
|
|
View PDF |
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. |
There are a few general steps to follow when using the Calendarlet classes:
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:
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 } } }
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(); }
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.