3 Building Applications with Oracle Discussions SDK

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.

Requirements

The following section shows you how to configure your environment. It describes the following tasks:

Setting Classpath
Passing Initial Context Parameters
Setting JAZN Permissions

Setting Classpath

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

Passing Initial Context Parameters

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: `discussions_<ocs-apps-instance-name> @<email-domain>` 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.

Setting JAZN Permissions

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-3 $ORACLE_HOME/oes/jazn/jazn.xml

<jazn provider="XML" location="./jazn-data.xml"/>

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>

Sample Code

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.

Example: Create Facility, Board, Thread, and Message

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();
       }
     } 
   }
 }

Configuring Properties

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.

Example: List Threads

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();
    }
  }
}

Example: List Grantee Roles

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();
    }
  }
}

Executing Sample Code

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.

Troubleshooting

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.

Oracle Discussions SDK Usage Tips

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.