SBO's, what and how?

I received some feedback on my previous blog on TBO's: http://www.docbyte.com/blog/creating-custom-tbo and a question that came back was: what are SBO's, and how are they connected with TBO's?

So in this tutorial, I'll try to do the following things:

• what is an SBO?
• how do you create an SBO?
• how do you use an SBO?
• provide a sample project

An SBO is a Service-Based Business Object.

"A service-based business object doesn’t map to a particular object type in the Docbase. Instead, it provides general purpose functions for your application to use. Service-based objects can be used across docbases, even accessing multiple docbases at once. These service-based objects are intended to be called from your own custom GUIs or as convenience functions from within your type-based objects.

Service-based objects were designed and optimized for multi-user, mutli-threaded, multi-docbase web applications." (dmdeveloper.com)

An SBO could do anything that doesn't specify to one object type:

• calculating and assigning a value
• adding a keyword
• generate a document
• ...

In my example I will create a simple SBO that will set the title to "Accessed from the SBO!" and add my name to the authors attribute from a sysobject.

Ofcourse this functionality is extremely simple in an actual situation your requirements would almost never be this simple.

To create your own SBO in Documentum Composer, follow these steps:

Create an interface IMyService that extends IDfService

public interface IMyService extends IDfService
{
//your method that executes your code
//it is possible to define more than one method

public void setAttributes(IDfSysObject sysObj, IDfSession session) throws DfException;
}

As you can see, I pass a sysobject to the SBO.  This is the object we will modify.
I also pass a session to the SBO.  This is not mandatory, as you can get a session from within the SBO.  It's just how I learned to do it.

Create the implementation class for your interface: MyService.  Make sure it extends DfService and implements your service.

 

public class MyService extends DfService implements IMyService
{
//implement your method(s) you have defined in the interface
public void setAttributes(IDfSysObject sysObj, IDfSession session) throws DfException
{
sysObj.setTitle("Accessed from the SBO!");
sysObj.setAuthors(sysObj.getAuthorsCount(), "Bart Thierens"
}
}

It's important to notice that I do not call sysObj.save() in the SBO.
Usually an object is not saved in an SBO, but it is ofcourse perfectly possible and it depends your requirements.
This is because SBO's are commonly called from within a TBO, and super.doSave(...) is called at the end.  And saving an object 2 times, is unneccessary time-wasting.

3. Package the interface and implementation in 2 different jars.

4. Create JAR Definition-artifacts for the 2 jars (ie. my_service_impl  and my_service_inter).

• If you have used thirdparty libraries, create jardefs for them aswell and put those in a Java Library-module.

5. Create a Module-artifact of type SBO.  I suggest using the full packagename of your interface as the SBO-name:

• com.mycompany.sbo.inter.IMyService.module
  I do this for consistency's sake.  Documentum also names its SBO's like that (check under /System/Modules/SBO and you'll see some standard SBO's).
  Also, in the past I have had some trouble with SBO's that couldn't be found.
  Use this approach and your SBO WILL work.

Also, in the Module artifact set the following data:

• Implementation JARs: my_service_impl and select your MyService class
• Interface JARs: my_service_inter
• Required Modules (optional): select other Modules if you have referenced them
  This can be the case when your SBO uses a specific TBO, or another SBO.
• Dependencies (optional): when your SBO uses thirdparty libraries, select the Java library

6. If you have entered the correct data, it's time to install the SBO.
Build the project, and install it in the repository.

To check if your SBO is installed:

• Browse to /System/Modules/SBO
• Check if your SBO is present
• If your SBO uses other modules or dependencies, you can check there if they are correct.

NOTE:

This is the approach when your repository is a global repository.  This is the case for most Documentum set-ups.

When your repository uses a separate global repository, you will need to install the SBO on the global repository.

If you don't, you will see similar errormessage like: Global registry does not know of service com.mycompany.sbo.inter.IMyService

Now, the SBO is ready and installed, but it's just sitting there.

We can use our SBO in a custom DFC application, or directly from another module (TBO or even another SBO). 
It is always done using the same approach.

To call an SBO from a TBO or DFC application, follow these steps:

1. Include the interface jar from the SBO in your classpath.

2.  type the following code in your TBO/DFC app:

IDfSession session = ...;
IDfSessionManager sessionMgr = session.getSessionManager();
IDfClient client = session.getClient();

String serviceName = IMyService.class.getName();

IMyService myService = (IMyService)client.newService(serviceName, sessionMgr);
myService.setAttributes(sysObj, session);

The serviceName variable should be the name you have given the SBO.  If you didn't give your SBO the name I suggested, you have to enter a different serviceName here.

3. That is all there is to it.

NOTE:

If you call the SBO from within a TBO or other SBO, you have to add the SBO as a required module.

I've included a demo project that contains

• an SBO (code, artifacts)
• a custom type (sbo_test_type) that has a custom TBO
• a TBO (code, artifacts) that uses the SBO 

To view the project, dowload it and change .txt to .zip.

Thanks for reading,
Bart