Oracle® Discussions Application Developer's Guide
10g Release 1(10.1.2) B28208-02 |
|
Previous |
Next |
This chapter shows you how to configure your environment in order to compile and execute applications that use Oracle Discussions SDK. It provides some example code for you to use.
This chapter assumes that you have access to an Oracle Collaboration Suite installation, and you know to set the Java classpath and compile and execute Java programs.
The following section shows you how to configure your environment. It describes the following tasks:
Include the following jar files in your classpath in order to compile and execute the sample code in this chapter. The path names in this list are relative to $ORACLE_HOME
:
discussions/lib/discussions.jar
j2ee/home/jazn.jar
j2ee/home/jazncore.jar
j2ee/home/lib/jms.jar
j2ee/OC4J_OCSClient/applications/discussions/lib/rtcSDK.jar
jdbc/lib/classes12.jar
jdbc/lib/ojdbc14.jar
jlib/collabsuiteuser.jar
jlib/esadmin.jar
jlib/escommon.jar
jlib/esldap.jar
jlib/esmail_sdk.jar
jlib/ldapjclnt10.jar
jlib/ocsaddressbook.jar
jlib/ocscommon.jar
jlib/ojmisc.jar
jlib/orai18n.jar
jlib/orai18n-js.jar
jlib/orai18n-ocs.jar
jlib/repository.jar
lib/activation.jar
lib/dms.jar
lib/mail.jar
lib/xmlparserv2.jar
workspaces/lib/workspaces_share.jar
See the following Java options according to your deployment. These initial context parameters control the behavior of Oracle Discussions.
Table 3-1 Initial Context Parameters as Java Options
Initial Context Parameter | Description |
---|---|
-Doracle.home=C:\TdDemo |
Base directory of your Oracle Discussions application |
-Doracle.ocs.ldappool.host=www.example.com |
Oracle Internet Directory hostname] |
-Doracle.ocs.ldappool.port=389 |
Oracle Internet Directory port |
-Doracle.ocs.ldappool.user_dn=cn=orcladmin |
Oracle Internet Directory login user name |
-Doracle.ocs.ldappool.user_password=welcome1 |
Oracle Internet Directory login user password |
-Doracle.ocs.ldappool.initialsize=1 |
Oracle Internet Directory LDAP pool size. Do not change the size. Default size is 1. |
-Doracle.ocs.ldappool.connectssl=false |
Specifies if the Oracle Internet Directory connection is to be secured. Default is false. |
-Doracle.mail.sdk.esmail.driver_type=thin |
Driver type to be used to connect to Oracle Mail store. |
-Doracle.mail.sdk.esmail.encryption=false |
Specifies whether or not encryption will be used by Oracle Mail |
-Doracle.discussions.event.enabled=false |
If set to false, the Oracle Discussions system will not post events |
-Doracle.discussions.tdadmin.email= discussions_ocs@example.com |
Oracle Discussions internal administrator email ID. This will be in the following form:
Log on to the Oracle Collaboration Suite Identity Management Self-Service Console to verify the existence of this user. The Applications tier instance name and the email domain are set when Oracle Collaboration Suite is installed. Refer to the Oracle Collaboration Suite installation log file for these details. |
Oracle Discussions uses Oracle Mail, which uses JAZN file protection for .jar file protection. Create or add to the following XML files in the indicated directories.
Ensure that you edit these files so that the Java library files that appear in the jazn-data.xml files point to the same Java library files in your classpath or else a SecurityException will be thrown.
Example 3-1 $ORACLE_HOME/j2ee/home/config/jazn.xml
<jazn provider="XML" location="./jazn-data.xml"/>
Example 3-2 $ORACLE_HOME/j2ee/home/config/jazn-data.xml
<jazn-data>
<!-- JAZN Realm Data -->
<jazn-realm>
<realm>
<name>jazn.com</name>
<users/>
<roles/>
</realm>
</jazn-realm>
<!-- JAZN Policy Data -->
<jazn-policy>
<grant>
<grantee>
<codesource>
<url>file:C:\TdDemo\lib\esldap.jar</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>
oracle.ias.repository.schemaimpl.CheckRepositoryPermission
</class>
<name>connectAs</name>
</permission>
<permission>
<class>
oracle.ias.repository.schemaimpl.CheckRepositoryPermission
</class>
<name>makeNewOIDEntry</name>
</permission>
<permission>
<class>
oracle.ias.repository.schemaimpl.CheckRepositoryPermission
</class>
<name>getIASProperty</name>
</permission>
<permission>
<class>
oracle.ias.repository.schemaimpl.CheckRepositoryPermission
</class>
<name>getOIDConnect</name>
</permission>
</permissions>
</grant>
</jazn-policy>
</jazn-data>
Example 3-4 $ORACLE_HOME/oes/jazn/jazn-data.xml
<jazn-data> <!-- JAZN Realm Data --> <jazn-realm> <realm> <name>jazn.com</name> <users/> <roles/> </realm> </jazn-realm> <!-- JAZN Policy Data --> <jazn-policy> <grant> <grantee> <codesource> <url>file:C:\TdDemo\lib\discussions.jar</url> </codesource> </grantee> <permissions> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>logon</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>minfo</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>procmparams</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>umparams</name> </permission> </permissions> </grant> <grant> <grantee> <codesource> <url>file:C:\TdDemo\lib\esldap.jar</url> </codesource> </grantee> <permissions> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>logon</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>minfo</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>procmparams</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>umparams</name> </permission> </permissions> </grant> <grant> <grantee> <codesource> <url>file:C:\TdDemo\lib\collabsuiteuser.jar</url> </codesource> </grantee> <permissions> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>logon</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>minfo</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>procmparams</name> </permission> <permission> <class>oracle.security.jazn.JAZNPermission</class> <name>umparams</name> </permission> </permissions> </grant> </jazn-policy> </jazn-data>
To create Oracle Discussions elements using Oracle Discussions SDK, first initialize a TdStore object for a particular user. This user must be a valid Oracle Discussions user and be provisioned for the same email domain as the Oracle Discussions internal administrator. Once a TdStore for a user is created, invoke Oracle Discussions API through that store. Each Oracle Discussions store is associated with a message store where Oracle Discussions elements are saved.
Before executing this example, create a user provisioned for the same domain as the Oracle Discussions internal administrator (in this example, the domain would be example.com). Grant this user global administrator role. This example uses a user with ID "tdga".
The following example creates a facility, creates a board inside the facility, posts a topic to the board, and replies to the topic.
Example 3-5 TdSampleClient.java
package oracle.discussions.demo; import java.io.*; import java.util.*; import javax.mail.internet.*; import oracle.discussions.sdk.*; import oracle.discussions.util.log.LogHandlerIf; import oracle.discussions.util.log.logger.WriterLogHandler; /** * Oracle Discussions Sample Code. */ public class TdSampleClient { TdStoreManager _tdStoreManager = null ; TdStoreFactory _tdStoreFactory = null ; public TdSampleClient() throws TdException { LogHandlerIf logh = null; try { // Initialize a file writer // to create a log handler logh = new WriterLogHandler( new PrintWriter(System.out)); } catch(Throwable t) { System.err.println( "ThreadedDiscussions: Could not initialize log handler: "+t); } // Initialize a new TdStoreManager // Set the logging level to the lowest Properties sysProps = System.getProperties(); Map mTdicProps = new HashMap(sysProps); // Change the following properties according to your deployment mTdicProps.put("oracle.ocs.ldappool.host", "www.example.com"); mTdicProps.put("oracle.ocs.ldappool.port", "389"); mTdicProps.put("oracle.ocs.ldappool.user_dn", "cn=orcladmin"); mTdicProps.put("oracle.ocs.ldappool.user_password","welcome1"); mTdicProps.put("oracle.ocs.ldappool.initialsize","1"); mTdicProps.put("oracle.ocs.ldappool.connectssl","false"); mTdicProps.put("oracle.discussions.log.level","debug"); mTdicProps.put("oracle.discussions.tdadmin.email", "discussions_ocs@example.com"); mTdicProps.put("oracle.discussions.event.enabled", "false"); mTdicProps.put(TdInitialContext.LOGGING_LEVEL, "debug"); mTdicProps.put(TdInitialContext.LOG_HANDLER_INSTANCE, logh); mTdicProps.put(TdInitialContext.APPLICATION_NAME, "td test"); TdInitialContext tdic = new TdInitialContext(mTdicProps); _tdStoreManager = TdStoreManager.createInstance(tdic); _tdStoreFactory = _tdStoreManager.getTdStoreFactory(); System.out.println("Created a handle to Store Manager succesfully"); } public TdStore getTdStore(String username) throws TdException { // // TdUserFactory tduf = TdUserFactory.getInstance(); TdUser tduser = tduf.getTdUserByNickname(username); return _tdStoreFactory.getTdStore(tduser); } public static void main(String argv[]) throws Exception { // Initialize Oracle Discussions by getting a TdStoreManager TdSampleClient tdsc = new TdSampleClient(); // Get a TdStore for a given user. // Ensure that this user exists and is provisioned for Oracle Mail // with the same domain as the Oracle Discussions internal administrator. TdStore tds = tdsc.getTdStore("tdga"); try { // Get a Facility TdFacility tdf = tds.getFacility("SampleFacility"); if (tdf == null) { tdf = tds.createFacility(null, "SampleFacility", "sample facility", "This is a facility created by Oracle Discussions sample code"); } // Create a board TdBoard tdb = tds.getBoard("/SampleFacility/SampleBoard"); if (tdb != null) { tdf.deleteBoard(tdb); } tdb = tdf.createBoard("SampleBoard", "Sample Board", "Board created by Discussions sample code"); // Use Board settings to specify board configuration options TdBoardSettings tdbs = tdb.getBoardSettings(); tdbs.setOutgoingEmailDL("marco.carrer@oracle.com"); tdb.updateContainerSettings(tdbs); // Post some of new threads MimeMessage mm = tdb.createMessageTopic(); mm.setSubject("New Thread Posted by Td Sample Client"); mm.setText("Hello!! This is a message posted " + "by the Oracle Discussions Sample Client"); tdb.appendMessage(mm); mm = tdb.createMessageTopic(); mm.setSubject("This is the latest thread posted " + "by the Oracle Discussions Sample Client"); mm.setText("Hello!! This is a new post"); tdb.appendMessage(mm); // Get all threads and append a reply to each one int i=0; TdIterator tdi = tdb.getThreads(); while (tdi.hasNext()) { TdThread tdt = (TdThread) tdi.next(); System.out.println("Thread "+(i++) +": "+tdt.getSubject()); // Post a new reply on each thread MimeMessage mmr = tdb.createMessageReply(tdt); mmr.setText("Hello to you too. This is my reply!!"); tdb.appendMessage(mmr); } // Favorites operations: // Add a favorite thread and get all threads tdi = tdb.getThreads(); TdThread tdt = (TdThread) tdi.next(); if (!tdt.isFavorite()) { tdt.addToFavorites(); } TdFavoriteManager tdfm = tds.getFavoriteManager(); TdIterator tdiFavTdts = tdfm.getFavoriteThreads(); int j=0; while (tdiFavTdts.hasNext()) { TdThread tdtFav = (TdThread) tdiFavTdts.next(); TdLastPost tdlp = tdtFav.getLastPost(); System.out.println("Fav Thread "+(j++) + ": "+tdtFav.getSubject()+ ". Last Post by "+tdlp.getLastPostAuthor()+ " on "+tdlp.getLastPostDate()); } } finally { if (tds != null) { tds.close(); } } } }
Set properties according to your deployment with the TdInitialContext class. The TdSampleClient.java example sets these properties in a hash map called mTdicProps. The following is a description of properties that have not been described in "Passing Initial Context Parameters":
Table 3-2
Property | Description |
---|---|
oracle.discussions.log.level |
Sets the logging level of Oracle Discussions. Set the log level to "info". This can be set to "debug" when debugging the application. The TdSampleClient.java example has set it to "debug". |
TdInitialContext.LOG_HANDLER_INSTANCE |
Creates a log handler and passes it to the Oracle Discussions server so that various activities can be logged. Refer to TdSampleClient.java to see how to create a logger. |
TdInitialContext.APPLICATION_NAME |
Passes the application name to Oracle Discussions. Various statements in the Oracle Discussions log file are generated using this application name. |
The following example lists information about each thread in a particular board. It uses the example TdSampleClient.java.
Example 3-6 TdThreadListingDemo.java
package oracle.discussions.demo; import java.io.*; import java.text.NumberFormat; import java.text.SimpleDateFormat; import java.util.*; import javax.mail.*; import javax.mail.internet.*; import oracle.discussions.sdk.*; import oracle.discussions.util.log.LogHandlerIf; import oracle.discussions.util.log.logger.WriterLogHandler; public class TdThreadListingDemo { public static void main(String argv[]) throws Exception { // Initialize Oracle Discussions by gettign a TdStoreManager // from TdSampleClient TdSampleClient tdsc = new TdSampleClient(); // Get a TdStore for a given user TdStore tds = tdsc.getTdStore("tdga"); try { // Get a Board TdBoard tdb = tds.getBoard("/Samplefacility/Sampleboard"); System.out.println("Board appears to be null! :" + (tdb == null) ); if (tdb != null) { System.out.println("Board appears to be null!"); TdThread tdt = null; TdIterator tdit = tdb.getThreads(); if (tdit != null) { for (int i = 0; i < tdit.size(); i++) { tdt = (TdThread)tdit.next(); System.out.println("Thread Subject :" + tdt.getSubject()); System.out.println("Is locked :" + tdt.isLocked()); System.out.println("Number of messages in this thread :" + tdt.getMessageCount()); System.out.println("Number of replies to this thread :" + tdt.getNumberOfReplies()); System.out.println("Is this thread a favorite for this user :" + tdt.isFavorite()); System.out.println("Thread Content :" + tdt.getBodyPlainText()); } } } } catch(TdException tdex) { tdex.printStackTrace(); } } }
The following lists the grantee roles of a particular user. It uses the example TdSampleClient.java.
Example 3-7 TdGranteeRoleListingDemo.java
package oracle.discussions.demo; import java.io.*; import java.text.NumberFormat; import java.text.SimpleDateFormat; import java.util.*; import javax.mail.*; import javax.mail.internet.*; import oracle.discussions.sdk.*; import oracle.discussions.util.log.LogHandlerIf; import oracle.discussions.util.log.logger.WriterLogHandler; public class TdGranteeRoleListingDemo { public static void main(String argv[]) throws Exception { // Initialize Oracle Discussions by getting a TdStoreManager // from TdSampleClient TdSampleClient tdsc = new TdSampleClient(); // Get a TdStore for a given user TdStore tds = tdsc.getTdStore("tdga"); try { List granteeRoles = tds.getGlobalAdminManager().listGranteeRoles(); if(granteeRoles != null) { TdGranteeRole tdgr = null; for (int i = 0 ; i < granteeRoles.size(); i++) { tdgr = (TdGranteeRole) granteeRoles.get(i); System.out.println("The User holding role :" + tdgr.getGrantee().getUserNickname()); System.out.println("The role :" + tdgr.getTdRole().toString()); System.out.println("Is this role inherited :" + tdgr.isInherited()); } } } catch(TdException tdex) { tdex.printStackTrace(); } } }
Compile each example with the following command:
javac -classpath $CLASSPATH <Fully qualified Java file name>
$CLASSPATH is the classpath environment variable to which all the Java library files listed in "Setting Classpath" are added.
<Fully qualified Java file name> is one of the samples in this chapter.
Execute each example with the following command:
java -cp $CLASSPATH <Fully qualified class file name>
<Fully qualified class file name> is one of the samples in this chapter qualified with its package name.
oracle.discussions.sdk.TdException: Cannot connect to Oracle Java Mail Store: javax.mail.NoSuchProviderException: esmail.
If you receive this exception, ensure that ojdbc.jar appears in your classpath.
oracle.discussions.sdk.TdException: The name for this Category is taken. Please choose a different name for the Category at oracle.discussions.sdk.impl.handler.ContainerHandler.createFacility
If you receive this exception, check the facility and board names and display names. The container you are trying to create might be the same as those already existing in the system. Change the name of the container you are trying to create and re-run the program. Both the name and display name must be unique for all containers at the same level.
java.lang.SecurityException: access denied
Ensure that the Java library files that appear in the jazn-data.xml files point to the same Java library files in your classpath.
The following are some programming tips when using Oracle Discussions SDK
Avoid hard-coding the Oracle Discussions internal administrator email address. Instead, retrieve this from Oracle Internet Directory.
Avoid granting the orclguest user the role of Oracle Discussions administrator.
You cannot use orcladmin to login to Oracle Discussions because orcladmin is not provisioned for any email domain.
Carefully double check the system parameters passed to the initial context of Oracle Discussions. Oracle Discussions behavior might vary depending on the initial context parameters passed to it.
Double-check JAZN permissions before executing the example code.