Connecting to UCM through RIDC

Tech stack

Implementation demonstrated in this blog is developed using JDeveloper – version 11.1.1.7.0

Use case

In this little blog we will look at how can we connect to a UCM server and make service calls through RIDC programmatically.

Implementation steps

Step 1: If not already done, install Webcenter plugin to you JDeveloper IDE. This can be done simply using Help menu option “Check for Updates”. In the dialog that appears search for webcenter extension and install it. Restart JDev when prompted.


Step 2: Create a new Webcenter project by accepting defaults or open an existing one in which you want to programmatically access the UCM services. Now create a new UCM connection like below. This will need detail of your UCM server to which you desire to connect and use in your application.

In the dialog that appears you need to fill in details about your UCM server. In general, important attributes to be filled are:

1. Connection Name: this can be anything you desire. 
2. Repository Type: Oracle Content Server 
3. Make sure you select the checkbox for “Set as primary connection for Documents service” 
4. Next in Configuration Parameters provide following: 
1. RIDC Socket Type: socket
2. Server Host Name: this will be the host name of the UCM server machine. If UCM instance is running on local then it will be localhost. Do not write http:// or port details here. Just the plain host name will do just fine.
3. Content Server Listener Port: 4444 (this is the default value for all UCM in general. If it is configured differently for your UCM then please provide the same)
4. Web Server Context Root: /cs
5. Test Connection: Test your connection to verify if its successful or not. In some cases you might also need to populate Admin Username and Admin Password fields in order to connect successfully.

Step 3: Now that we have setup a UCM connection we will see how to access it programmatically. Although the API to establish connection and fire a service call itself is pretty compact, it is always best to create a separate class which will implement all required helper APIs to cater to your project requirements (establishing connection using singleton approach, reading a file, updating a file metadata, upload an image/logo/document etc). This decision will depend upon your design so we will not dwell in that here.

Following is a simple class which establishes a connection and fires a standard UCM service request:

public class MyUCMService {
 static String ucmURL = "idc://dummy.com:4444";    
    private static DataBinder dataBinder;
    private static IdcClient idcClient;
    private IdcContext userContext; 
    private static String ucmAdminUser = "myadminuser";
    private static String ucmAdminPassword = "myadminpass";

    static {
            IdcClientManager manager = new IdcClientManager();
            try{
            idcClient = manager.createClient(ucmURL);
            dataBinder = idcClient.createBinder();
                           } catch (IdcClientException e) {
                                throw new ContentServiceException("Error in request IdcClient: " + e.getMessage(), e);
                           }
    }

    public MyUCMService() {
            userContext = new IdcContext(ucmAdminUser, ucmAdminPassword);
    }

    public InputStream getDocumentByName(String dDocName) throws Exception{
        if (dDocName == null)
            return null;
       
        try {
            dataBinder.putLocal("IdcService", "GET_FILE");
            dataBinder.putLocal("dDocName", dDocName);

            ServiceResponse response = idcClient.sendRequest(userContext, dataBinder);
            InputStream is = response.getResponseStream();
            return is;
        } catch (Exception e) {
            throw new Exception("Unable to get input stream for DocName "+dDocName+" Message: "e.getMessage(),e);
        }
    }
}

In above code snippet, we have demonstrated how we can establish a UCM connection and also how to invoke most commonly used GET_FILE service.

The constructor is responsible for initializing user context which will be followed by static block execution that prepares the DataBinder object. DataBinder object is responsible to set key request attributes – like what is the IdcService that you want to invoke (in our case GET_FILE), what all parameters/metadata the service need to use in order to prepare UCM query (in our case dDocName) etc.

Depending on the service, you can pass many parameters. Ultimately, sendRequest() method is used to fire the UCM request. On the UCM end it will decode the userContext and dataBinder objects to establish authorization and execute the desired operation.

Response is returned in the form of ServiceResponse object which can be used to read through the result set arriving as a result of query. This response object can be used to iterate through data objects or simply read the input stream (as we did). If you want to iterate through data objects returned then do something like below:

DataBinder responseDataBinder = response.getResponseAsBinder();
DataResultSet dataResultSet = responseDataBinder.getResultSet("SearchResults");
for (DataObject dataObject : dataResultSet.getRows()) {
 title = dataObject.get("dDocTitle");
}

Please note that there is a wide range of services that UCM provides in order to operate programmatically. You can refer following link to learn them: https://docs.oracle.com/cd/E23943_01/doc.1111/e11011/c04_core.htm#CSSRG2076

We hope you now have a fair knowledge of how to take advantage of UCM services programmatically and if you have any doubts/questions feel free to drop in your comments.

Until next time, Happy Coding !