| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14477-01 |
|
|
View PDF |
| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14477-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.
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.
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
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
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,
"username",
"password",
"http://www.example.com/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 11, "Oracle Calendar Web Services Client-Side Java Implementation" 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
public class MyFetchTest
{
public MyFetchTest() { }
public void run()
{
try {
// Initialize the event search command and query
oracle.calendar.soap.client.SearchCommand search =
new oracle.calendar.soap.client.SearchCommand();
search.setCmdId("MySearchCommandID-1");
// Create a query to retrieve unconfirmed 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);
// 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();
Initialization myInit = new Initialization();
myInit.initBasicAuth(
cws,
"username",
"password",
"http://www.example.com/ocws-bin/ocas.fcgi");
// Make the SOAP call
oracle.calendar.soap.client.CalendaringResponse response
= cws.Search(search.getElement());
// Get the SOAP reply
oracle.calendar.soap.client.Reply reply =
(oracle.calendar.soap.client.Reply)
response.getCalendarReply();
// Traverse all the iCalendar objects
java.util.Vector someiCalendars =
oracle.calendar.soap.iCal.iCalendar.unmarshallVector(
reply.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();
System.out.println
("iCalendar " + i + ", vCalendar " + j + ", vEvent " + k + ":");
System.out.println("Title: " + title);
System.out.println("Start time: " + dtstart);
System.out.println("End type: " + dtend);
System.out.println("Event type: " + eventType);
// Do something interesting with the meeting info
}
}
}
} catch (Exception e)
{
System.out.println("Exception enountered:");
System.out.println(e.getMessage());
e.printStackTrace();
}
}
/**
* Main method
*
*/
public static void main(String[] args)
{
MyFetchTest myFetchTest = new MyFetchTest();
myFetchTest.run();
}
}
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 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 calendar 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 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.
