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:

1. 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.

2. 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 a TBO 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