|
Oracle® Discussions Application Developer's Guide
10g Release 1(10.1.2) B28208-02 |
|
 Previous |
 Next |
|
Oracle® Discussions Application Developer's Guide
10g Release 1(10.1.2) B28208-02 |
|
|
Previous |
Next |
Oracle Discussions SDK contains Java API that allow you to create and manage Oracle Discussions elements. These API are exposed through the package oracle.discussions.sdk.
This chapter describes the elements of Oracle Discussions SDK and the Java classes that represent them. It also describes other classes that help manage and configure Oracle Discussions elements.
Some elements and functions in Oracle Discussions are represented with a new terminology in Oracle Discussions SDK. The following table describes the names of Oracle Discussions elements and functions as they appear in the Web client, and the corresponding name that is used in the Oracle Discussions SDK.
Table 2-1 Names Used in Oracle Discussions Web Client
| Name Used in Web Client | Name Used in SDK |
|---|---|
|
Category |
Facility |
|
Forum |
Board |
|
Topic |
Thread |
|
Hide |
Delete |
|
Replies to my posts |
TdMyFollowups |
Oracle Discussions SDK facilitates the creation of the following Oracle Discussions elements:
A store allows a particular Oracle Discussions user to create, delete, and access Oracle Discussions facilities and boards. A store provides methods for the following:
Creating and deleting containers
Initializing global settings
Initializing various managers such as TdGlobalAdminManager and TdSubscriptionManager
Searching Oracle Discussions facilities and boards
Oracle Discussions will create a store at login time for every valid Oracle Discussions user. This store will be closed when the user logs out. A store is an abstraction of a Discussions root container. Every user that logs into Oracle discussions has a store associated with him or her.
The Oracle Discussions store is represented by TdStore.
The TdUser class represents Oracle Discussions users. These users must be provisioned for a valid email domain to be able to access Oracle Discussions. A user is anyone who is provisioned with an Oracle Collaboration Suite account.
The factory class TdUserFactory factory class retrieves Oracle Discussions users from Oracle Internet Directory, based on a user attribute such as email address or global user identifier (GUID).
The TdUserProfile class represents an Oracle Discussion user's profile. This profile includes personal information (such as address, phone number, and picture), and basic statistics (such as last login time and number of posts). Access a user's profile with the TdUserProfileManager class.
An Oracle Discussions container is represented by the TdContainer class. This class is the super class of TdFacility and TdBoard. It stores attributes and properties common to both facilities and boards.
TdContainerPermissions represents an Oracle Discussions user's permissions on a container. It specifies the actions and operations that a user can perform on the container. The TdContainerSettings class represents the container attributes defined when the container is created.
A facility is a container that holds other facilities or boards. It may not contain threads or messages. However, the boards stored in a facility may contain threads or messages. The TdFacility class represents a facility. Facilities are uniquely identified among all other facilities at the same level by their name and display name.
The TdFacilityPermissions class represents the actions the logged in user may perform on a facility.
A board is a container that holds threads and messages. It may not contain facilities or other boards. The TdBoard class represents a board. Boards are uniquely identified among all other boards at the same level by their name and display name.
The TdBoardPermissions class represents an Oracle Discussions user's permissions on a board. It specifies the actions and operations that a user can perform on the board. The TdBoardSettings class represents the board attributes defined when the board is created, such as maximum attachment size and board email address.
By configuring a board's settings, it can be viewed as an IMAP folder in an email client. As a result, any messages posted from the email client and addressed to the board will appear as Oracle Discussions messages in the board, and threads and messages posted to the board will appear as email messages in the user's inbox.
The TdAnnouncementsBoard class represents special board to which messages can be posted only by the board moderator. An announcements board is present in the Oracle Discussions root container by default. When creating any other facility or board, you may specify whether or not it will contain an announcements board.
An announcements board is implicit. It always has a name ".Announcements" (note the period before this name). It is always public, meaning that any user who is a member of the container in which announcements board is present can read the messages in it. Once created, an announcements board cannot be edited. Announcements board cannot be locked like any other board.
The TdThread class represents a thread in a board. A root topic in a board is a thread and the subsequent replies to this root topic are messages. This class extends the TdMessage class.
The TdThreadPermissions class represents an Oracle Discussions user's permissions on a thread. It specifies the actions and operations that a user can perform on the thread. These actions and operations depend on the user's role as defined in the thread's parent container.
The TdMessage class represents a message in a board. This class provides methods to move and delete a message and retrieve information about a message, such as the message's parent thread, parent board, attachments, and body.
The TdMessagePermissions class specifies the actions a user may perform on a message. These depend on the user's role as defined in the parent container of the message and whether the user is the owner of the message.
To obtain a list of attachments of a particular message, call TdMessage.getAttachments(). This will return a list of TdAttachment objects. This class holds metadata about the attachment, including the attachment's name and size. Instead of holding the actual content of the attachment, it holds the attachment's ID, which can be passed to the TdMessage.getAttachmentById() method to fetch the attachment itself.
The TdFlag represents status flags for messages. This class represents the following flags:
NEW_SINCE_LAST_VISIT: This flag is set if the message is new since the time the user last logged out.
NEW_SINCE_SESSION: This flag is set if the message is new since the user's current session.
To retrieve all the messages posted by a user throughout the Oracle Discussions system and in all forums, call the TdStore.getMyPosts() method. This returns an instance of TdMyPosts.
To retrieve the last posted message (most recently posted message) at a particular container level, call TdFacility.getLastPost() or TdBoard.getLastPost(). To retrieve the most recently posted message in the entire Oracle Discussions system, call the TdStore.getLastPost().
To retrieve the most recent posts or most popular threads of a particular user the replies to messages of a particular user, call TdStore.getLastMessagePosts() or TdStore.getPopularThreads(), respectively. Both these methods return iterators. These calls are also available at container levels.
To retrieve the replies to the user-posted messages, call TdStore.getMyFollowups(). The method returns the replies posted by other Oracle Discussions users to the logged in user's posts.
The following features allow you to manage and administer the elements of Oracle Discussions SDK:
The following access control roles have been defined:
Global administrator: Users granted this role represent the super users of the system. They are granted the permission of executing all tasks on all objects in the system.
Facility creator: These users can create new facilities and boards within the facility for which they are granted this role. Facility creators are automatically granted facility administrator and board administrator roles for the facilities and boards they create.
Facility administrator: Facility administrators have permission to administer only the facilities and boards within the assigned facility. Facility administrators can post announcements for the facility they administer.
Facility writer: These users automatically have board writer privileges for all the board within the facility for which they are granted this role.
Facility reader: These users automatically have facility reader privileges for all the boards within the facility for which they are granted this role.
Board creator: Board creators on a given facility have the privilege of creating boards within that facility.
Board administrator: Users granted this role on a given board have the authority of managing the content within that board. Board administrators can post announcements for the forum they moderate.
Board writer: Board writers can post new topics or reply to existing ones. They may be able to edit messages that they posted (depending on board policies), but never messages posted by other users.
Board reader: Board readers will only have read access to boards on which they have been granted the role. Board readers do not have permission to post new messages or reply to existing topics.
The TdRole class represents a role. To grant or revoke a role to a user, call the grant and revoke methods in the TdGlobalAdminManager class.
To retrieve a list of users and their roles for a particular facility or board, or to retrieve users and their roles from the entire Oracle Discussions system, call the listGranteeRoles() method from the respective TdFacility, TdBoard, or TdStore instance. This will return a list of TdGranteeRole objects. This class associates a user with a role.
When you call a method that returns a collection of Oracle Discussion elements, such as TdBoard.getThreads(), which retrieves all the threads of a particular board, the method will return an iterator. Use this iterator to traverse through the list of returned Oracle Discussion elements.
A favorite is an Oracle Discussions element of user's interest. These favorites are listed at the global level and at each container level, which allows users quick access to them.
The TdContainer and TdThread classes implement the TdFavorite interface. Therefore, you may add or remove a container (facility or board) or thread from the user's favorites by calling the element's addToFavorites() or removeFromFavorites() methods.
Retrieve a complete list of a user's favorite threads in the entire Oracle Discussions system by using an instance of TdFavoriteManager, retrieved from a TdStore instance. This class also gives access to the user's favorite containers in the entire system.
To search for a message in a particular facility or board, call the search() method. This method takes a oracle.discussions.sdk.TdSearchTerm object as an argument to represent the query criteria of a search. It returns an array of TdMessage objects.
To search for a message globally, call the TdStore.search() method. This method takes a TdSearchTerm object as an argument to represents the query criteria of a search. The TdStore.search() method returns a TdIterator.
Subscriptions allow users to monitor the changes to Oracle Discussions elements without actually logging into Oracle Discussions. When a user subscribes to an Oracle Discussions element, he or she will receive a notification email whenever that element is changed until that user unsubscribes from that Oracle Discussions element, or that element is deleted.
To subscribe to an Oracle Discussions element, obtain an instance of TdSubscriptionManager from TdStore and call the manager's subscribe() method.
The TdSubscription class represents a user's subscription to a container. The TdThreadSubscription class represents a user's subscription on a thread. To obtain an instance of either of these classes, call TdSubscriptionManager.getSubscription() with the subscribed container or thread as an argument.
An annotation represents an Oracle Discussions operation performed on a message or thread. It represents a message modification history. An annotation stores information such as the user performing the operation, the operation being performed, and the date on which the operation is being performed.
The TdAnnotation class represents an annotation. Retrieve all the annotations of a message with the TdMessage.getAnnotations() method.
Oracle Discussions returns the following exceptions:
TdRuntimeException: Represents general Oracle Discussions runtime exceptions
TdUnsupportedOperationException: Represents runtime exceptions thrown for JavaMail operations not supported by Oracle Discussions
TdException: Represents general Oracle Discussions exceptions
TdConfigurationException: Thrown when supplied configuration parameters to the Discussions initial context are not correct.
These features help configure Oracle Discussions:
The TdInitialContext class represents the initialization parameters provided to Oracle Discussions SDK. This class inherits from java.util.HashMap. The supplied properties will determine the behavior of Oracle Discussions in terms of infrastructure services to use such as logging and Oracle Internet Directory authentication.
Grant or revoke global administrator's or root level facility creation privileges to a user with the TdGlobalAdminManager class. Obtain an instance of this class from TdStore.getGlobalAdminManager().
Change system-level properties with the TdGlobalSettings class. See the section Tuning Oracle Discussions in the chapter "Monitoring and Tuning Oracle Collaboration Suite Performance" in Oracle Collaboration Suite Administrator's Guide for a list of these properties.
