Service Based Objects (SBO’s) in Documentum


Documentum Business Object Framework which was introduced from Documentum 5.3 plays a key role in most of the current Documentum implementations.  Service based Object is one of the important member of Documentum BOF family.  Lets try to see what makes Service Based Objects very popular and how can you implement it.

What is a SBO

In simple terms SBO in Documentum can be compared to session beans of J2EE environment.  SBO enable the developers to concentrate just on the business logic and all the other aspects will be managed for you by the server. This reduces the application code significantly and reduces lots of complexities. The biggest advantage of a BOF that its deployed in a central repository. The repository maintains this module and DFC ensures that he latest version of the code is delivered to the client automatically.

Service Based Objects are repository and object type in-depended that means the Same SBO can be used  by multiple Documentum repositories and can It can retrieve and do operations on different object types. SBO’s can also access external resources for example a Mail server or a LDAP server. Prior to the introduction of Documentum Foundation Services SBO’s were commonly used exposed to expose documentum web services.

An SBO can call another SBO or by any Type based Objects. (Type Based Objects (TBO) are a different kind of Business Object types which I will explain in a different study note)

A very simple to understand example for a SBO implementation would be a Zip code Validator. Multiple object types might have Zip code across multiple repositories.  So if this functionality is exposed as a SBO it can be used by the custom application irrespective of Object types and repositories. This Validator SBO can be used even by different TBO’s for validations.

Here are some bullet points about SBO’s for easy remembering

  • SBO’s are part of Documentum Business Object framework
  • SBO’s are not associated with any repositories
  • SBO’s are not associated with any Documentum object types.
  • SBO information is stored in repositories designated as Global Registry.
  • SBO’s are stored in /System/Modules/SBO/<sbo_name> folder of repository. <sbo_name> is the name of SBO.
  • Each folder in /System/Modules/SBO/ corresponds to a individual SBO

How to implement a SBO using Composer

The steps to create a SBO are these.

1) Create a interface that extends IDfService define your business method
2) Create the implementation class implement write your business logic, This class should extend DfService and implement the interface defined in Step 1
3) Create a jar file for the created Interface and another jar for the implementation class then create Jar Definitions
4) Create a SBO Module and Deploy your Documentum Archive using Documentum Composer (Application builder for older versions)

Lets see these steps with an Example SBO Zip Code Setter, I am not covering the steps using application builder here. The screenshots and the notes will give you an insight about how to use Documentum Composer to implement a Service Based Object in Documentum version 6 or above.

Step 1 : Create an interface and define your Business method

The first step is to create a interface which will define the business functionality. This interface should extend IDfService interface. Client application will use this interface to instantiate the SBO.

Click New –> Interface in Documentum Composer. Click on the Add button of Extended Interfaces and search for IDfService. Select IDfService and click OK

image

Now Add the Business method ValidateZipCode() to interface. The code should look like the following.

package com.ajithp.studynotes.sbo;

import com.documentum.fc.client.IDfService;

import com.documentum.fc.client.IDfSysObject;

import com.documentum.fc.common.DfException;

public interface IZipValidatorSBO extends IDfService {

 public void validateZipCode (IDfSysObject obj, String zipCode, String repository)throws DfException;

}
Step 2 : Create the implementation class

All the Service Based Object implementation classes should extend from DfService class and implement the Interface created in the first step.  DfService class is an abstract class There are few methods which were abstract in 5.3 and has provided with a default implementation in 6.0 and later

Method Name Returns More information
getVendorString() String This method’s default implementation returns a empty String. Override to make changes to it.
getVersion() String This method returns a version which is not right, Override this method to return Major.minor version.
isCompatible() boolean The default implementation returns true if the version is an exact match

Lets see some other important methods of DfService Class before we move further.

Method Name Returns More information
getName() String This returns the fully qualified logical name of the service interface
getSession() IDfSession This method returns IDfsession Object for the docbase name which is passed as argument to this method. You have to make sure that you call releaseSession() after you are done with the operation that involves session.
releaseSession()   Releases the handle to the session reference passed to this method.
getSessionManager() IDfSessionManager Returns the session manager.

Managing repository sessions in SBO As We saw the the previous table its always good practice to release the repository session as soon as you are done with its use. So the ideal way to do this should be like this.

// Get the session 

IDfSession session = getSession(repoNam);

try {

// do the operation with session

} catch (Exception e){

// Process the exception 

}finally {

// release the session 

releaseSession(session)

}

Transactions in SBO

Another important thing is to know is  how to handle transactions in SBO. Note that only session manager transactions can be used in a SBO. System will throw an Exception when a session based transaction used within a SBO.

beginTransaction() will start a new Transaction and use commitTransaction() to commit it or abortTransaction() to abort a transaction.  Always ensure that you are not  beginning a transaction where another transaction is active. You can use isTransactionActive() to find out whether a transaction is active or not.

Another important point is if your SBO doesn’t start a transaction don’t commit it or abort it in the SBO Code instead if you want to abort the transaction use setTransactionRollbackOnly() method.

Other important points

1) Since SBO’s are repository independed do not hard code the repository names in the methods. Either pass the repository name as method parameter or have it as a variable in SBO and use a setter method to populate it after instantiating

2) Always try to make SBO’s stateless (Its a pain to manage state full SBO’s ).

3) Don’t reuse SBO, Always create a new instance before a operation.

Now lets see how to code our ZipSetterSBO

Click on New –> Class, Click on the Browse button of Superclass and Search and Select DfService and in the Interfaces search for the Interface created in the previous step and Click OK. Also select the option Inherited Abstract Methods in Which method stubs would you like to create.

image

I had Overriden method getVersion() for the illustration purpose. See the code sample for the inline comments.

package com.ajithp.studynotes.sbo.impl;

import com.ajithp.studynotes.sbo.IZipValidatorSBO;

import com.documentum.fc.client.DfService;

import com.documentum.fc.client.IDfSession;

import com.documentum.fc.client.IDfSysObject;

import com.documentum.fc.common.DfException;

public class ZipValidator extends DfService implements IZipValidatorSBO {

public static final String versionString = "1.0";

// overriding the default 

public String getVersion() {

return versionString ;

  }

public void validateZipCode (IDfSysObject obj, String zipCode, String repository) throws DfException {

     IDfSession session = getSession(repository);

     try {

     if (isValidUSZipcode(zipCode)){

         obj.setString("zipcode",zipCode);

         obj.save();

 }

     } catch (Exception e){

 /* Assuming that transaction is handled outside the code and this says DFC to abort the transaction

  in case of any error */

 getSessionManager().setTransactionRollbackOnly();

 throw new DfException();

     } finally {

 releaseSession(session);

    }

  }

private boolean isValidUSZipcode(String zipCode){

// implement your logic to validate zipcode. 

// or even call a external webservice to do that 

 // returning true for all zip codes

 return true;

  }

}
Step 3 : Generate Jar files and Create Jar Definitions

The next  step in SBO creation is to create Jar files which will hold the interface and the implementation classes. These jar files are required to deploy your SBO.

Use Composers/Eclipse Create Jar option or command line jar command to create the jar file

image image

image

Selecting the sbo package to create the interface jar

image

Selecting the com.ajithp.studynotes.sbo.impl for implementation.

Look at the Composers Export Jar screenshots for Interface and implementation (Refer Eclipse Documentation for more details). I think the figures posted above are self explanatory.

The Command line to create a Jar file is jar cf <name_of_jar> Please look at the Java Documentation for more details on switches and options  of Jar command.

The creation of Jar Definitions are new step added in Composer.

1) In Composer change the perspective to Documentum Artifacts Click New –> Other –> Documentum Artifacts –> Jar Definition

image

2) Click Next  and Enter the name of for the Jar Definition and click Finishimage

3) Select Type as Interface if the jar has only interface , Implementation if the jar has only implementation of interface or Interface and Implementation if the single jar file has both interface and implementation. click on the Browse button and browse to the jar created in the last step.

In Our case create two Jar Definitions The first one with type as Interface pointing to Jar Created for SBO and second one with type Implementation pointing to the implementation jar

untitled

Name the Interface jar def as zipcodevalidator and the implementation jardef as zipcodevalidatorimpl

Step 4 : Create a Module and Deploy the SBO

In Composer change the perspective to Documentum Artifacts then Click New –> Other –> Documentum Artifacts –> Module

image

Give a valid name and leave the default folder and Click Finishimage

In the Module edit window select SBO from the dropdown

image

Now Click on Add Section of Implementation Jars of Core Jars. A new pop up window will appear which will have list of all the Jar definitions set to Type Implementation and Interface and Implementation. Select the one you wanted to use for ZipCodeValidatorSBO that is ZipCodeValidatorImpl.

image

Click on the Select Button near pointing to Class name and Select the implementation class. In this case ZipValidator

image

Now Click on Add Section of Interface Jars of Core Jars. A new pop up window will appear which will have list of all the Jar definitions set to Type Interfaces and Interface and Implementation. Select the one you wanted to use for ZipCodeValidatorSBO that is ZipCodeValidator.

image

For more details of other options refer to Documentum Composer Manual. Save the Module.

Now right click on the project and install the Documentum project

image

Click on the Login button after logged in Click on Finish to start the installation.

image

 

Look at the Documentum composer documentation to know more about the Installation options.

How to use SBO from a Client Application

follow the below steps to instantiate a SBO from a client application.

1) Get the Local client

2) Create a login info and populate the login credentials.

3) Create a IDfSessionManager object

4) Use the newService () from the Client Object to create a SBO instance

// create client

  IDfClient myClient = DfClient.getLocalClient();

  // create login info

  IDfLoginInfo myLoginInfo = new DfLoginInfo();

  myLoginInfo.setUser("user");

  myLoginInfo.setPassword("pwd");

  // create session manager

  IDfSessionManager mySessionManager = myClient.newSessionManager();

  mySessionManager.setIdentity("repositoryName", myLoginInfo);

  // instantiate the SBO

  IZipValidatorSBO zipValidator = (IZipValidatorSBO) myClient.newService( IZipValidatorSBO.class.getName(), mySessionManager);

  // call the SBO service

  zipValidator.validateZipCode(obj, zipCode, "repositoryName");    

Download this Study Note (PDF)

Advertisements

Object Types involved in WorkFlow


Below is the table with different object types that has some role in workflow (5.3) with its description from Documentum Object Reference Manual

Object Type

Short Description

Detailed Information

dm_workflow

Contains the runtime information about a workflow.

A workflow object contains the runtime information about a workflow.

dm_activity

An activity object defines a workflow activity.

The attributes in an activity object define who performs the activity and the packages and work items generated from the activity.

dm_process

A process object contains the definition of a workflow process.

A process object is created when a user creates a workflow definition in either Workflow Manager or Business Process Manager. There are three inherited attributes that are reserved for internal use for process objects: a_special_app, a_status, and a_application_type.

dmi_workitem

Stores information about a task for a human or automatic performer.

Work items are generated by Content Server from an activity object. Users cannot create work items. Users can modify only the following attributes: a_held_by, a_wq_doc_profile, a_wq_flag, a_wq_name, and a_wq_policy_id.

dmc_workqueue

Represents a work queue for work items generated from a workflow

A work queue object represents a work queue for workflow tasks. The workqueue object type is installed by a script when Content Server is installed. However, work queues (instances of the type) are created and managed using Webtop.

dmc_workqueue_category

Defines a category for a work queue.

A work queue category object represents a category of work queues. The object type has no attributes defined for it. It inherits all its attributes from its supertype, dm_folder. It uses only the object_name, acl_name, and acl_domain attributes. The object_name attribute stores the work queue category name

dmc_workqueue_policy

Defines configuration information for a work queue.

A work queue policy object defines configuration parameters for handling a task in a  workqueue. The parameters control how the items are handled. Each work queue has one associated work queue policy. If a document associated with a task has a defined work queue policy, that policy overrides the work queue’s policy.

dmi_wf_timer

Records the configuration of a timer for a workflow activity.

A wf timer object describes a timer for a workflow activity. The wf timer objects are created automatically when the timer is instantiated.

Download This Study Note (PDF)

Aspects the new BOF type in Documentum


Aspects

Aspects, the new member in the BOF family is one among the new additions to the Documentum 6 (D6).  This short notes are just to give you insight to the fundamentals of Aspects.

What is Aspects?

In simple words Aspects are like TBO’s but they are not associated with any object types.  That means you can attach or detach an Aspect at runtime to any object type. In other words Aspects are a mechanism for adding behavior and/or attributes to a Documentum object instance without changing its type definition (From DFC Study Guide)

Aspects like any other BOF types are stored in the repository. When a DFC runtime requests for a Aspect it will be downloaded to that system and used. Aspect belongs to the type dmc_aspect_type.

 Aspects are saved in /System/Modules/Aspect in the repository which has a global registry. If any changes are made to any aspects DFC runtime detects that and downloads the latest version to its local cache of BOF.  

What Aspects can do?

Aspects are different from other BOF’s because it is attached to the Object instance, not to the object types.  They are not a per-application customization. Any Persistent object instance can have multiple aspects attached to it if each aspect has a unique name.

Aspects define custom additional fields and it can set custom values to the fields of any object that of type persistent object. There are no restrictions for the type of and number of attributes that you can create on an aspect.  It can be of any supported types and be either a single value or a repeated value attributes.

Another aspect can access the Attributes defined in one Aspect. The Fully qualified aspects attributes are aspect_name.aspect_value. When you fetch an Object all values of attributes of attached aspects are also fetched.  If you destroy an object it also deletes the attributes in the attached aspect.

Where Can I use it?

Aspects are used when you have a cross type functionality to be defined. When you create a application infrastructure or a corporate platform Aspects are the best way to implement business functionality which is common between different object types. When you have some functionality that is per instance based then also Aspects is the solution.

Lets see a real time scenario where you can use Aspect.

Lets imagine a scenario where you have system, which has user base of different countries, depending upon the country where a user belongs the behavior and fields of the application changes. You can create different aspect, which has the country specific behaviors and fields, and attach it as needed. If the user changes from one country to another simply remove the old country aspect and attach the new country aspect.

 To be Continued ….