| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25489-01 |
|
|
View PDF |
| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25489-01 |
|
|
View PDF |
This chapter discusses the following topics to be taken into consideration in your Oracle Calendar SDK implementations:
The Oracle Calendar SDK provides standards-based wrappers around a subset of Oracle Calendar core functions. It should be used for rapid development of utilities and applications that extend the existing Oracle Calendar applications, and not as a tool to replace existing interfaces or logic.
The SDK has been used to integrate with portals, FCGI-based applications, and even simple command-line scripts which might display a day's events. The SDK is best used to achieve a specific goal.
All SDK functions operate only on UTF-8 encoded text. All strings given to the SDK functions must be in UTF-8 and all strings returned by the SDK will be in UTF-8. For more information on UTF-8, refer to RFC 3629.
There are two parts to the security model: storing and fetching events. These are handled by different security paradigms.
The owner of an event can add or delete properties of that event. When an "ATTENDEE" property is created for a calendar user, the property is created with default values for its parameters. The owner of the event cannot modify the parameters of that property, only the user to whom it corresponds can do that.
When a user is updating their "ATTENDEE" property no error will be returned if there is an attempt to modify other event data, but the modifications will not occur.
It is possible for a user to refuse invitations from another user. In that case an "ATTENDEE" property will not be created for that user and the status for that user's handle will indicate that the invitation was refused. This may also occur when attempting to double book resources.
When fetching events the security model is based on the iCalendar classification of the event. Users grant other users different access levels to different classes of events. The three access levels are: no read access, read the start and end times of the event only, and read all details of the event. When fetching events with the SDK this results in some events for which only the "UID," "DTSTART," "DURATION" and "DTEND" properties will be returned. All other events will be invisible or all of their properties will be returned.
The Oracle Calendar SDK does not allow users to modify the security records which govern this behavior.
Unlike many Oracle products, the Oracle Calendar SDK (nor Oracle Calendar Web services) does not filter data entered by users for malicious HTML that could be used for breaching security layers, such as cross-site scripting attacks. As such, it is the responsibility of any application that retrieves data from the Oracle Calendar server to ensure that user data is properly filtered before it is displayed in a Web browser.
The Oracle Calendar SDK identifies users with a user identification string. The format of this string flexible and allows you to specify a number of optional parameters. Depending on the server configuration, some of these options (such as the Node ID) may be required in the user identification string. The same user identification string format is used both at logon and when obtaining a handle; however not all options will be applicable in both cases.
Logging into the server as a resource is not supported, but it is possible to work as a designate for a resource.
A user identification string consists of a user ID string followed by a question mark (?) and a series of key-value pairs. This series of pairs is called the extended data. (In the above example, the user ID has not been defined.)
The Oracle SDK can identify calendar users with the user ID string or a search string that looks for specific information in the extended data, such as the user's email address.
With a standalone Oracle Calendar server, the Oracle Calendar administrator sets the user ID string individually per user. As a result, the administrator may choose to leave the user ID string blank, as in the above example.
This user ID string is mapped to an LDAP attribute, typically uid. You may determine which attribute this is by looking at the file ocal/misc/unison.ini. In the LDAP section, look for the attr_uid key.
The key-value pairs of the extended data are separated by a delimiter. This delimiter is the character following the question mark (?) of the logon string. The delimiter may be any ASCII character except a digit, a letter, NUL, asterisk (*) or equal sign (=). Key-value pairs consist of a field name, followed by an equal sign (=), which is followed by the value. The value is a string that does not contain the delimiter character, the NUL character, and, for user identification strings, the slash (/) character. The logon string is terminated by a delimiter followed by a NUL character.
The following is a legal string for identifying a user:
?/S=Bunny/G=Bugs/
The field name G denotes the given name, and S denotes the surname. No user ID string is specified, so the extended data will be used to search for the user. (Note that if a search results in multiple matches, the SDK will return an error to the caller; a user ID is the best method of specifying a user, if it is available.) Even with no user ID, the question mark (?) still separates the user ID string from the extended data. The character immediately following the question mark, in this case a slash (/), is used as the delimiter. Note that the string ends with the delimiter character.
Any field used for identifying a user may be terminated with an asterisk (*), which is used as a wildcard. This is not available for specifying nodes. For example, the following will match the preceding user:
?/S=Bu*/G=Bugs/
Remember that if multiple users match a given search string, the SDK call will return an error.
The following is an example of an identification string of a calendar resource:
?/RS=CA:MTRL:ConferenceRoomName/
Calendar resources use the same string format as those for calendar users, except that calendar resource identification strings must define at least the field "RS" that indicates the resource's name.
Logging into the Oracle Calendar server as a resource is not supported, but it is possible to work as a designate for a resource.
The following grammar (in ABNF form, as described in RFC 2234) describes legal identification strings. The description diverges from ABNF in that values in double quotes are case-sensitive; for example, field names must be in uppercase. Also, the delimiter character must be the same in all cases in a single string.
Example 2-1 Oracle Calendar SDK Identification Strings Grammar
logon-string = ( userid [ "?" DELIMITER node DELIMITER] %x00
/ "?" DELIMITER 1*(x400-field) [node DELIMITER] %x00
/ "?" DELIMITER resource-name DELIMITER [node DELIMITER] %x400
/ "?" DELIMITER email DELIMITER [node DELIMITER] %x00
/ "?" DELIMITER guid DELIMITER [node DELIMITER] %x00 )
userid = *( ALPHA / DIGIT / "-")
x400-field = ( surname / given-name / initials / generation / org-unit
/ organization / country / admin / private ) DELIMITER
email = "EMAIL=" 1*VALUE-CHAR
resource-name = "RS=" 1*VALUE-CHAR ["*"] DELIMITER
guid = "GUID=" 1*VALUE-CHAR
node = "ND=" node-number
node-number = 1*DIGIT
surname = "S=" 1*VALUE-CHAR ["*"]
given-name = "G=" 1*VALUE-CHAR ["*"]
initials = "I=" 1*VALUE-CHAR ["*"]
generation = "X=" 1*VALUE-CHAR ["*"]
org-unit = ( "OU1" / "OU2" / "OU3" / "OU4" ) "=" 1*VALUE-CHAR ["*"]
organization = "O=" 1*VALUE-CHAR ["*"]
country = "C=" 1*VALUE-CHAR ["*"] DELIMITER
admin = "A=" 1*VALUE-CHAR ["*"] DELIMITER
private = "P=" 1*VALUE-CHAR ["*"] DELIMITER
DELIMITER = %x01-%x29 / %x2B-%x2F / %x3A-%x3C / %x3E-%x40 / %x5B-%x60
/ %x7B-%x7F
VALUE-CHAR = %x01-29 / %x2B-2E / %x30-7F
Specifying a particular field more than once is, while redundant, still legal, although only the last field will be used.
Note also that the DELIMITER cannot be used as a VALUE-CHAR.
Also note that the SDK identification strings parser does not validate guid and email strings for correctness; it accepts these strings as long as it passes these strings on as-is, as long as they don't break the user string format.
The following are examples of identification strings:
Table 2-1 Oracle Calendar SDK Identification Strings
| Type (as specified by logon-string) | Example |
|---|---|
|
userid |
tjefferson |
|
x400-field |
?/G=GERMAINE/S=LAUZON/I=/X=/OU1=/OU2=/OU3=/OU4=/ O=Vision Corp./C=CA/A=/P=/ |
|
resource-name |
?/RS=CA:MTRL:ConferenceRoomName/ |
|
|
?/EMAIL=fred.flintstone@bedrockquarry.com/ |
|
guid |
?/GUID=F934D040EC9D4ABCE030578C82100D80/ |
The Oracle Calendar SDK uses the iCalendar data types DATE, DATE-TIME and DURATION.
Identifies values that contain a calendar date. For example, September 28, 2002 would be represented by the following:
20020928
Identifies values that specify a precise calendar date and time of day. It may be in either floating time or UTC time. Floating time uses the user's timezone (the user's timezone preference stored on the Oracle Calendar server).
For example, the following floating time value represents September 29, 2002, at noon:
20020929T120000
The following UTC time value represents September 29, 2002 at 1700 UTC:
20020929T170000Z
The Oracle Calendar SDK disregards (and does not store in the Oracle Calendar store) any seconds (the last two digits) in DATE-TIME values. However, the seconds are still mandatory for this format.
Identify properties that contain a duration of time. For example, the following represents five days and three hours in the future:
+P5DT3H
The following represents one week in the past:
-P1W
Alarms are considered private to each user, so users cannot read or write alarms for each other. Since users cannot read each other's alarms it is not possible for users to do fetches by alarm range on each other's calendars. Any user may set an alarm for an event which they are attending, so the same events can have a different alarm when fetched by a different user.
By default, the SDK deals with MIME (see RFC 2045) encapsulated iCalendar and vCard objects for both input and output. A single request may fetch data from a list of calendars. A reply to such a request will consist of a separate iCalendar object for each calendar in the list, inside separate MIME parts. That is, a request for events from calendar A and calendar B results in a MIME stream of this form:
MIME envelope --MIMEBOUNDARYasdfasdf Content-type: text/calendar Content-Transfer-Encoding: quoted-printable BEGIN:VCALENDAR events from calendarA END:VCALENDAR --MIMEBOUNDARYasdfasdf Content-type: text/calendar Content-Transfer-Encoding: quoted-printable BEGIN:VCALENDAR events from calendarB END:VCALENDAR --MIMEBOUNDARYasdfasdf--
A blank line separates the MIME header from the body (which in this case would be an iCalendar object).
The order of the iCalendar objects corresponds to the order of the calendars in the request list. If a request results in an empty solution set, the return stream will be an empty iCalendar object. If there is any sort of error with a calendar the iCalendar reply object corresponding to that calendar will be empty.
On a successful fetch the "VCALENDAR" may contain many "VEVENT" components, each containing the requested properties, if available. iCalendar allows these different components to contain information about different instances of the same event. The returned data may use any of the following methods to give instance specific information:
Data for each instance can be placed in a different "VEVENT" component, with a different "DTSTART".
Data for multiple instances can be placed in a single "VEVENT" by identifying instances with the properties "RRULE", "RDATE", "EXRULE" and "EXDATE"
Hybrids of the preceding two methods allow grouping of multiple instances which share all properties except their start time in a single "VEVENT" component, and returning many such components.
Note that the "DTSTART" property returned indicates the start time of the first instance identified in the "VEVENT" component in which it resides and not the start time of the first instance of the event in the Oracle Calendar store. Furthermore the number of "VEVENT" components returned in the calendar has no relation to the number of instances of the event. Consequently, when fetching events, if the recurrence identifying properties are not requested, there will be no way to determine how many instances exist, and to which instances each returned property applies.
When storing, data supplied to the Oracle Calendar SDK must consist of a single "VCALENDAR" component inside a single MIME part. The calendar may contain many "VEVENT" objects, but these must all be information about a single event. For example, this is a valid input:
Content-type: text/calendar Content-Transfer-Encoding: 7bit BEGIN:VCALENDAR VERSION:2.0 BEGIN:VEVENT event properties END:VEVENT BEGIN:VEVENT event properties END:VEVENT END:VCALENDAR
Access to data through the SDK is controlled by the Oracle Calendar server. It is based on the requester's identity and the data or operation being requested. The SDK provides an interface to request reading any combination of properties. Properties that the requesting user is not authorized to read will not be returned.
Users will only have privileges to modify the events to which they are invited, or which they own. If the user is the owner of the event they will have full privileges to modify the event (except for modifying other users' attendance information), otherwise if they are invited to the event they will have restricted privileges to modify information relating to their own attendance, such as acceptance and alarms.
Errors may occur for specific agendas when attempting to modify events or when creating events. These errors will be returned using a supplied array of status values, allowing the rest of the operation to proceed.
Session and handle usage has to be considered when designing multi-threaded applications with the C and Java Oracle Calendar SDK.
No two threads should concurrently use a session or handle object, even if the threads are performing operations on the same user's agenda or handle: The SDK does not support the concurrent use of sessions and handles.
If a possibility exists that two threads could use the same session object, it is the application's responsibility, using its own synchronization functionality, to guarantee that the same session will not be used concurrently by both threads.
The following scenario describes what might happen if a thread uses a session and a handle at the same time:
Both Thread1 and Thread2 use Session1.
Thread1 authenticates as User1.
Thread2 then deauthenticates and reauthenticates as User2.
Thread1 still assumes it is authenticated as User1 and inadvertently performs operations on User2.
