Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25489-01 |
|
|
View PDF |
This chapter describes the design of the set of Java classes used to provide contextual collaboration through the access of calendar data through Oracle Calendar Web services. These "Calendarlet" classes attempt to hide the many details of using Web services technology in a Java environment.
See Oracle Calendar Web Services Java API Reference for more information about these classes.
The class implementation does not attempt to provide all the iCalendar properties and attributes.
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:
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.
In order to use Oracle Calendar Web services, the following .jar files must be in your classpath:
$ORACLE_HOME/j2ee/home/lib/*
$ORACLE_HOME/ocal/jlib/ocal_clnt.jar
$ORACLE_HOME/soap/lib/soap.jar
$ORACLE_HOME/lib/xmlparserv2.jar
The following code uses basic authentication to create one event or Web conference. This code consists of the following classes:
Initialization: Connects to the Oracle Calendar server with basic authentication
MyEventCreateTest: Creates one event or Web conference depending on the value of the parameter isWebConference in the MyEventCreateTest constructor.
Example 11-1 Initialization.java
package oracle.test.cal; public class Initialization { public Initialization() { } public void initBasicAuth( oracle.calendar.soap.client.Calendarlet cws, String name, String password, String endPointURL) { cws.setEndPointURL(endPointURL); cws.setWantIOBuffers(true); // Initialize the authentication information oracle.calendar.soap.client.authentication.BasicAuth auth = new oracle.calendar.soap.client.authentication.BasicAuth(); auth.setName(name); auth.setPassword(password); // Set the basic authentication header cws.setAuthenticationHeader(auth.getElement()); } }
Example 11-2 MyEventCreateTest.java
parckage oracle.test.cal; public class MyEventCreateTest { private oracle.calendar.soap.iCal.vEvent vevent; private String currentEventGUID; private String k_startTime; private String k_baseDuration = "PT01H00M"; private String k_baseLocation = "Tecumseh, Ontario"; private String m_testName = "Event Create Test"; private String m_uid = "UID-TEST-1"; private String m_eventClass; private String m_xEventType; private String m_cmdid = "CMDID-TEST-CREATE-1"; private String m_cmdid_delete = "CMDID-TEST-DELETE-1"; private boolean m_isWebConference; public oracle.calendar.soap.iCal.vEvent getvEvent() { return vevent; } public String getEventGUID() { return currentEventGUID; } public MyEventCreateTest() { } public MyEventCreateTest( String startTime, String duration, String location, String summary, String UID, String eventClass, String xEventType, String commandID, boolean isWebConference) { k_startTime = startTime; k_baseDuration = duration; k_baseLocation = location; m_testName = summary; m_uid = UID; m_eventClass = eventClass; m_xEventType = xEventType; m_cmdid = commandID; m_isWebConference = isWebConference; } public void run() { try { // Create the iCalendar that is to be // created on the Oracle Calendar server oracle.calendar.soap.iCal.iCalendar ical = new oracle.calendar.soap.iCal.iCalendar(); oracle.calendar.soap.iCal.vCalendar vcal = new oracle.calendar.soap.iCal.vCalendar(); vevent = new oracle.calendar.soap.iCal.vEvent(); ical.addvCalendar(vcal); vcal.addvComponent(vevent); // set the vEvent attributes vevent.setEventClass(m_eventClass); // Start time vevent.setDtStart(k_startTime); // Duration vevent.setDuration(k_baseDuration); // Location vevent.setLocation(k_baseLocation); // Summary vevent.setSummary(m_testName); // UID vevent.setUid(m_uid); // Event type vevent.setXEventType(m_xEventType); // Description vevent.setDescription(ical.toString()); // Make this event enabled for Web conference if (m_isWebConference) { vevent.setWebConferenceEnabled(true); vevent.setWebConferenceType(vevent.k_webConferenceTypePublic); } // Initialize the event create command oracle.calendar.soap.client.CreateCommand create = new oracle.calendar.soap.client.CreateCommand(); create.setCmdId(m_cmdid); create.setiCalendar(ical); // Create the Oracle Calendar client SOAP stub // and set the basic authentication header System.out.println("Creating the Oracle Calendar client SOAP stub"); oracle.calendar.soap.client.Calendarlet cws = new oracle.calendar.soap.client.Calendarlet(); // Login if (cws == null) { return; } Initialization myInit = new Initialization(); myInit.initBasicAuth( cws, "loginuser", "password", "http://www.example.com:7777/ocws-bin/ocas.fcgi"); // Next, make the SOAP call System.out.println("Making the SOAP call"); oracle.calendar.soap.client.CalendaringResponse response = cws.Create(create.getElement()); // Now display the results System.out.println("SOAP send buffer:"); System.out.println(response.getSendBuffer()); System.out.println("SOAP receive buffer:"); System.out.println(response.getReceiveBuffer()); // Get the created event's GUID oracle.calendar.soap.client.CreateReply myCreateReply = null; try { System.out.println("Creating CreateReply"); myCreateReply = (oracle.calendar.soap.client.CreateReply) response.getCalendarReply(); } catch (Exception e) { myCreateReply = null; } if (myCreateReply == null) { System.out.println("Unable to create CreateReply"); // There is nothing to do return; } currentEventGUID = myCreateReply.getDataGuid(); } catch (Exception e) { System.out.println("Exception enountered:"); System.out.println(e.getMessage()); e.printStackTrace(); } } /** * Main method * */ public static void main(String[] args) { MyEventCreateTest myEventCreateTest = new MyEventCreateTest( "20050714T040000Z", "PT01H00M", "Somewhere exotic", "MyEventCreateTest8", "MyEventCreateTest-UID-8", oracle.calendar.soap.iCal.vEvent.k_eventClassPublic, oracle.calendar.soap.iCal.vEvent.k_eventTypeAppointment, "CommandID-MyEventCreateTest", true); myEventCreateTest.run(); } }
To create a Web conference, create an event with the following properties
<x-oracle-isrtcenabled> set to true
<x-oracle-rtc-securitytype> set to the security type of the Web conference. This can be either "REGULAR", "PUBLIC", or "RESTRICTED".
<dtstart> set to a time in the future
<summary> set to a short description of the Web conference
You may also configure the following Web conference properties:
See Chapter 12, "Oracle Calendar Web Services Supported Data Components and Properties" for more information about these properties.
The following sample code performs the following:
Creates a query that searches for all events within a date range of one week starting on today's date
Uses basic authentication services to connect to the Oracle Calendar server
Traverses through all iCalendar objects. Traverses through all vCalendar objects in each iCalendar object. Traverses through all vEvent objects in each vCalendar object, and outputs information about each vEvent object.
This code consists of the classes Initialization (which is listed previously) and MyFetchTest.
Example 11-3 MyFetchTest.java
package oracle.test.cal; public class MyFetchTest { public MyFetchTest() { } public oracle.calendar.soap.client.Reply run( oracle.calendar.soap.client.Calendarlet cws) { try { // Initialize the event search command and query oracle.calendar.soap.client.SearchCommand search = new oracle.calendar.soap.client.SearchCommand(); search.setCmdId("MyUpdaeTestCommandID-1"); // Create a query to retrieve events oracle.calendar.soap.client.query.vQuery query = new oracle.calendar.soap.client.query.vQuery(); query.setFrom (oracle.calendar.soap.client.query.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 java.util.Calendar today = oracle.calendar.soap.client.CalendarUtils.getToday(); int dayOfWeek = today.get(java.util.Calendar.DAY_OF_WEEK); java.util.Calendar beginWeek = (java.util.Calendar)today.clone(); java.util.Calendar endWeek = (java.util.Calendar)today.clone(); beginWeek.add(java.util.Calendar.DATE, 1 - dayOfWeek); endWeek.add(java.util.Calendar.DATE, 8 - dayOfWeek); endWeek.add(java.util.Calendar.MINUTE, -1); // Use the CalendarUtils to help generate a date range query query.setWhere (oracle.calendar.soap.client.CalendarUtils.getDateRangeQuery (beginWeek, endWeek)); search.setQuery(query); // Make the SOAP call oracle.calendar.soap.client.CalendaringResponse response = cws.Search(search.getElement()); // Now display the results System.out.println("SOAP send buffer:"); System.out.println(response.getSendBuffer()); System.out.println("SOAP receive buffer:"); System.out.println(response.getReceiveBuffer()); // Get the SOAP reply oracle.calendar.soap.client.Reply reply = (oracle.calendar.soap.client.Reply) response.getCalendarReply(); return reply; } catch (Exception e) { System.out.println("Exception enountered:"); System.out.println(e.getMessage()); e.printStackTrace(); } return null; } public String outputReply ( oracle.calendar.soap.client.Reply replyArg) { String returnString = ""; // Traverse all the iCalendar objects java.util.Vector someiCalendars = oracle.calendar.soap.iCal.iCalendar.unmarshallVector( replyArg.getEntries()); int numiCalendars = someiCalendars.size(); for (int i = 0; i < numiCalendars; i++) { oracle.calendar.soap.iCal.iCalendar iCalObj = (oracle.calendar.soap.iCal.iCalendar) someiCalendars.get(i); // Traverse all the vCalendar objects java.util.Vector somevCalendars = iCalObj.getvCalendars(); int numvCalendars = somevCalendars.size(); for (int j = 0; j < numvCalendars; j++) { oracle.calendar.soap.iCal.vCalendar vCalObj = (oracle.calendar.soap.iCal.vCalendar) somevCalendars.get(j); // Traverse all the vEvent objects java.util.Vector somevEvents = vCalObj.getComponents(); int numvEvents = somevEvents.size(); for (int k = 0; k < numvEvents; k++) { oracle.calendar.soap.iCal.vEvent vEventObj = (oracle.calendar.soap.iCal.vEvent)somevEvents.get(i); // Get the specific properties String title = vEventObj.getSummary(); String dtstart = vEventObj.getDtStart(); String dtend = vEventObj.getDtEnd(); String eventType = vEventObj.getXEventType(); returnString += "iCalendar " + i + ", vCalendar " + j + ", vEvent " + k + ":" + "\n"; returnString += "Title: " + title + "\n"; returnString += "Start time: " + dtstart + "\n"; returnString += "End type: " + dtend + "\n"; returnString += "Event type: " + eventType + "\n"; // Do something interesting with the meeting info } } } return returnString; } /** * Main method */ public static void main(String[] args) { // Create the Oracle Calendar client SOAP stub // and set the basic authentication header oracle.calendar.soap.client.Calendarlet cws = new oracle.calendar.soap.client.Calendarlet(); // Specify login username, password, and host Initialization myInit = new Initialization(); myInit.initBasicAuth( cws, "loginuser", "password", "http://www.example.com:7777/ocws-bin/ocas.fcgi"); MyFetchTest myFetchTest = new MyFetchTest(); oracle.calendar.soap.client.Reply mainReply = myFetchTest.run(cws); System.out.println(myFetchTest.outputReply(mainReply)); } }
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 13, "Oracle 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 Oracle 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 date information. DateTime is generally used for regular meetings, while Date is used for Day Events, Daily Notes, and Holidays.
To generate UTC datetime strings for a vQuery, use the CalendarUtils.getUTCDateTime method. It takes a standard Java Calendar class object and generates a string of the form yyyyMMdd
T
hhmmss
Z
. 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 object.
// 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 generate UTC date strings for a vQuery, use the CalendarUtils.getUTCDate method. It takes a standard Java Calendar class object and generates a 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 object.
// 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 calendar query operations are relative to today's date, an additional CalendarUtils method is provided to help base vQuery datetime stamps. The method returns a datetime stamp of midnight today, local time of the form yyyyMMdd
T
hhmm
00Z
, wherehhmm
is the hour and minute offset from UTC (note that some time zones are half-hour offsets).
String utcToday = CalendarUtils.getToday();
Typical Oracle 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.