What Is the Business Objects Framework?
The
Business Objects Framework
BOF is a set of functionality introduced in Documentum 5.1 that allows developers to extend the Documentum Foundation Classes (DFC). You can think of it as a layer on top of DFC that allows you to add your own business logic; all of the existing DFC methods and behaviors are still available, BOF simply gives you some additional (and much needed) features. Although we think of BOF as being a layer on top of DFC, it is actually only a logical separation. BOF is included as part of DFC 5.1 – it is in fact intrinsically interwoven into DFC.
The main purpose of BOF is to act as a business logic middleware layer for your applications. Prior to DFC 5.1, Documentum did not provide any middleware tools. BOF is Documentum’s attempt to give developers a framework on which to add customer-specific extensions.
Another important thing to note is that BOF was developed and optimized for web-based applications. There are several features that make it easy to use BOF within an application server, such as trusted logons and connection pooling. However, you will also get huge value out of BOF if you are creating a client server application or customizing the Desktop Client.
Benefits of BOF
There are several benefits of using the Business Object Framework, providing an enhanced development environment for building and maintaining Documentum systems.
- Reduced Development Time – Because Documentum provides this framework for implementing business logic, you do not have to develop and maintain your own framework.
- Abstraction of Business Logic from Presentation – Separating the business logic from the presentation layer has two main benefits. First, it allows you to have a different team implementing the presentation layer than the one implementing the business logic. Second, if changes must be made to the business logic, you will not have to make changes to the presentation layer; you only need to redeploy your Business Objects.
- Encourages Reuse – Business Objects are designed to be reused. Because they are part of DFC, any application that uses DFC can use your Business Objects (including Desktop Client, Office Integrations, and WebTop)
- Portable Across Applications – Because Business Objects are written in Java, they can be deployed on multiple platforms, and again, they can be deployed across all the Documentum clients that use DFC.
When to Use BOF
If you are doing any non-trivial Documentum-related development, you are probably going to want to use Business Objects. Not only will your code be available in multiple Documentum clients, but you will no longer have to re-integrate your customizations whenever Documentum releases a new version of the client.
Even if you are not planning to support multiple clients, you should still probably use the BOF. It forces you to use object-oriented principals and to keep the business logic out of the GUI layer, both of which are good things. Also, we expect to see the BOF becoming a more and more important part of Documentum’s development methodology, so the sooner you become familiar with it, the better.
If you are developing a web-based application that accesses a docbase, you will absolutely want to use the Business Objects Framework. The BOF was created with web application developers in mind, and there are enough performance improvements and conveniences offered by the framework that it will certainly be worth your time to learn about it.
Key Features
Polymorphism
Polymorphism is an object-oriented programming term. If a programming environment supports polymorphism, it means that different types of objects can behave differently when the same method is called on them. A system that supports polymorphism treats sub-classes the same as it treats superclasses and allows the programmer to modify the methods of the subclass that are inherited from the superclass. The syntax of the method stays the same, but the implementation changes. For example, if a method acts on a widget object, you can also pass that method a sub-class of the widget object. And if the widget object has a method named foo(), you can create your own foo() method on the sub-class that does something different.
In Documentum 4.x, DFC didn’t really support polymorphism (at least not from the point of view of a developer using DFC to create an application). You could not sub-class DFC objects or extend their behavior. Clever programmers would get around this by creating their own objects that implement the same interfaces as the DFC objects. But in this case, they would have to re-implement every method in the DFC object’s interface. This is a real pain.
However, with the addition of BOF, you can now sub-class DFC objects and extend them to either override existing methods or add your own methods. You don’t have to re-implement every method – you only need to re-implement the methods that you want to override.
Object Factory Guarantee
An
object factory
is design pattern where one object (the factory) creates other objects. Factories are used to prevent programmers from explicitly declaring the implementation class in their code. Instead, programmers declare the interface that they are using and have the factory instantiate the implementation class.
DFC has always used an object factory to create the Java objects that you use in your code. You have never been able to create a DFDocument directly, you always have to use the factory to create one.
WRONG: DFDocument doc = new DFDocument();
RIGHT: IDFDocument doc = sess.newObject("dm_document");
The main drawback to this approach is that in version 4.x, even if you were a clever programmer and rolled your own object that implemented the IDFDocument interface, there was no way that your object would get used by any existing DFC applications. Since all the applications used the object factory, and the object factory only created Documentum’s objects, your custom objects would never get created.
In DFC version 5.1, this shortcoming is rectified. You can now tell DFC’s object factory to create your custom objects instead of the normal DFC objects. As a result, existing Documentum applications such as Desktop Client and WebTop will be able to call all the custom business logic you include in your custom business objects. This is accomplished through the use of the Documentum Business Object Registry. If your objects have been registered with DBOR, the object factory guarantees that your custom object will be created and used whenever it is appropriate.
Documentum Business Object Registry (DBOR)
The
Documentum Business Object Registry
(DBOR) allows developers to “register” their custom business objects with DFC’s object factory. The DBOR maps your custom Documentum object type (in the eContent Server) to your custom business object Java class.
Once registered, DFC will automatically create and use your business object whenever it is dealing with a document object belonging to that custom object type. The object factory guarantees that this will happen.
To register a business object with an object type, you can use the
DborManage
tool provided with DFC or you can manipulate the DBOR registry with a new dbor object in DFC.
Session Management / Session Pooling
With the Session Manager, DFC 5.1 provides some new functionality for managing and pooling DFC sessions. The
SessionManager
is a new object in DFC that assists the developer with managing stateful and stateless Docbase connections. This new functionality provides a convenient way of taking advantage of the connection pooling features offered in the DMCL.
As you may remember, Documentum introduced DMCL-level connection pooling in version 4.2. The main advantage of this connection pooling was to drastically reduce the time that it takes to connect to the Documentum server. With this faster connection time, web developers were encouraged not to keep prolonged sessions with the Docbase. Instead of creating a DFC session and storing it in an App Server session variable for the duration of a user’s session with the web application, developers would connect to Documentum at the top of each JSP page and disconnect at the bottom of each JSP page. Since the cost of connecting is nominal using DMCL connection pooling, this approach is a really good way to conserve server resources. Instead of maintaining overhead for every active user, the Documentum server only needs to maintain a connection while a JSP page is executing. No connection is maintained while the user is reading the resulting page.
The drawback of this approach is that in order to connect at the top of each JSP page, you must know the user’s username and password. This means that you have to store that information in an app server session variable, which is a bit of a security risk. The DFC 5.1 Session Manager alleviates that problem.
The Session Manager is basically a convenience class for connecting and disconnecting to the Docbase. When a user logs into your web application, you create a Session Manager object using the user’s username and password. Then whenever your code needs to interact with the Docbase, you simply ask the Session Manager for a session. Under the covers, the Session Manager will connect to the Docbase for you. When you are finished interacting with the Docbase, you release the session back to the Session Manager. After a certain amount of idle time, the Session Manager will disconnect from the Docbase for you.
In a multi-threaded application, each thread must have its own connection to the Docbase in order to avoid stepping on each other’s Docbase connection. In previous versions of DFC, developers had to have their own code to ensure that each thread had its own session or that the threads never used a common session at the same time. In DFC 5.1, the Session Manager makes this easier by automatically creating a new session for each thread that uses it.
Simply put, using the Session Manager is really the key to building scalable Documentum-based web applications.
Cross-Docbase Transactions
Another nice feature of DFC 5.1’s BOF is the ability to have transactions that span docbases. If a developer starts a transaction in one Docbase and then connects to a second Docbase to do some additional work, the Session Manager will automatically start a transaction in the second Docbase. Whenever the original transaction is committed or aborted, the Session Manager will commit or abort the transaction in the second Docbase as well.
Java Cache of Object Attributes Independent of Docbase Session
One of the limitations of DFC has always been that in order to use a DFC object, you must be connected to the Docbase in which the object lives. The implications of this are that all operations on an object must take place on a machine that contains a DMCL. For example, if an applet wants to access a Documentum object in order to display some of its properties, that applet must either connect to DFC locally (as the DocAdmin applets do), or developers must create an adapter class that copies the attributes out of the DFC object into an object that the applet can interact with.
In version 5.1, however, the DFC allows developers to manipulate DFC objects independent of DFC sessions via the setSessionManager() method. This method will copy the attributes out of the DMCL cache and store them in the DFC object itself. The developer can now safely release the Docbase session and still use the getters and setters on the object. If the developer were to call the save() method on the object, DFC will reconnect to the docbase in order to save the updates.
There is a performance penalty for this, however, since every attribute is cached in the DFC object and there is overhead in the JNI calls used to communicate between DFC and the DMCL.
Types of Business Objects
There are two types of business objects,
Type-Based Objects
(TBOs) and
Service Based Objects
(SBOs).
Type-Based Objects
Type-based business objects (TBOs) are the most common types of business objects. They correspond to custom object types in the Docbase and used to apply custom business logic to those object types. You create a TBO by extending a DFC object such as DFDocument.
Type-based objects allow developers to override the typical DFC methods to add validation logic or change the way that the original methods behave. You can also add your own custom methods for your own purposes. Because all objects are created via the object factory, your TBO is guaranteed to be used even by existing Documentum clients.
TBO Example – Custom Validation Logic
There are many ways that type-based objects can be used. One of the most common uses is to apply custom validation logic that goes beyond what the data dictionary provides. For example, imagine that you have created a custom object type in your Docbase called a report. This object type has two custom attributes, report_type and report_number. You have set up value assistance for the report_type attribute, creating a list of the types of reports your organization creates. This list contains three possibilities: Marketing Report, Engineering Report, and Research Report. Marketing and engineering reports can have arbitrary report numbers that are specified by the author of the report. But research reports must have report numbers that follow very specific rules. In this case, the report number for a research report must be unique and it must already have been created in the Research Department’s report database
Let’s examine how we would enforce this rule using Documentum 4.x. You might first attempt to use the data dictionary, but this will not work. Unfortunately, the attribute constraints provided in the data dictionary can not have conditional logic; you can not have the constraint for report_number depend on the value of report_type. Also, you can not make the data dictionary fire off a script to check with the research department’s database.
Therefore, in version 4.x, you must customize the properties dialog GUI in order to add this logic. Unfortunately, you will have to customize the dialog for every application you use: Desktop Client, Intranet Client, WebPublisher, etc. And each time that Documentum upgrades one of these applications, you will have to re-integrate your customizations into the new version.
In version 5.1, however, enforcing these validation rules is much easier. You would simply create a business object java class to represent your report. To do this, you extend the existing DFDocument object. To insert your custom validation logic, you re-implement the save() and checkinEX() methods, adding your custom code to check for uniqueness and query the external database. Don’t forget to call the superclass method to actually do the save or checkin once the validation is complete. After you register this object with the DBOR, all of the existing Documentum clients will begin to use your new code. You don’t have to make any GUI modifications at all.
Service-Based Objects
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.
An example of a service-based object is an object that determines if an attribute value is unique. This SBO could be used from within our report business object described in the example above. The SBO would take four arguments: Docbase name, object type, attribute name, and attribute value. When invoked, the SBO would establish a session with the Docbase (using the session manager) and would query the object type to determine if the specified attribute value already existed. This way, multiple TBOs could call the same SBO to check for attribute uniqueness without duplicating this code in every TBO. You would probably even want the SBO to connect to the Docbase as a superuser so that the query is run with superuser permissions.
Currently, there are not many service-based objects being provided by Documentum. However, in the future, this will change. For example, all of the business logic in WebPublisher 5.1 is being developed using BOF. This means that developers will be able to override the existing WebPublisher SBOs with their own to change the behavior of WebPublisher.
A Real-Life Example
Let’s wrap things up by looking at a real life example that I encounter on customer projects all the time. I’ll describe the business problem, show you how we have solved it using Documentum 4.x, discuss and how we will solve it using the Business Objects Framework. You can decide for yourself which method you think is better.
Problem Definition
When most organizations implement Documentum, they organize their documents into a series of folders and sub-folders that help the users browse around and find their documents. These companies also create custom attributes that help users search for the documents. In many cases, the folder structure corresponds to the values in some of these attributes.
For example, imagine that we have a document type with three custom attributes: department, product_name, and document_type. Our folder structure for storing the documents is laid out starting with department name, followed by product name, followed by document type. Here’s a sample folder structure that shows this layout:
Figure 1:
Sample Folder Structure
And here’s the properties dialog for a document stored in the /Marketing/Super Widget/Brochures folder.
Figure 2
You can see that the attributes of the document correspond to its location in the folder structure. In order to create the document, the user must navigate the folder structure to choose the document’s location. In this case, the user opens the Marketing folder, then the Super Widget folder, then the Brochures folder. When the user creates a new document, the properties dialog is displayed and the user has to enter the correct attributes. So the user chooses Marketing for the department, Super Widget for the product name, and Brochures for the document type.
Doesn’t this seem like the double entry? The user already indicated what type of document they were creating by selecting the folder. They should not have to repeat this step when entering the attributes.
To solve this problem and prevent the user from having to enter the same information twice, our plan is to create a customization that will set the attribute values based on the folder within which the document is being created. We use several Documentum client applications at our company, including the Desktop Client, Intranet Client, the MS-Office Integrations, and some eConnectors such as the Lotus Notes eConnector and the CADLink eConnector. Our customization must work for documents created using any of these applications.
Solving the Problem in 4.x
To set the attributes of a document based on the folder path using 4.x, we must modify the GUI controls of the applications we are using, adding the logic to read the folder path and set the attributes. To make this customization to the Desktop Client, we must modify the dcNew component using Visual Basic. To make this customization in the Intranet Client, we must modify the new action in RightSite’s WebQL language. To make this customization in the Office Integrations, we must modify the Office Integration’s New component in C++. And unfortunately, it is not possible to customize the Notes or CADLink eConnectors at all, since these are third party integrations and the source code is not distributed.
So to implement this customization, we have to write code in three different programming languages and still can’t deploy our customization to all of our Documentum clients. In addition, since we are modifying the GUIs of these applications, we will have to re-apply our customizations each time Documentum releases an upgrade to any of these products. Obviously, this is not an optimal solution to the problem.
Solving the Problem using BOF
Deploying this customization using version 5.1 is much simpler, thanks to the Business Objects Framework. We would simply create a business object for our custom object type and override the new() method. The logic to set the attributes based on the folder path will be called from the overridden new() method. Since all of the clients we need to support use DFC, our customization can be written in one language (Java), and it will be called from all of the client applications, even the third-party integrations.
What’s Missing?
The Business Objects Framework is a huge productivity boon for Documentum developers, but it’s not a panacea. There are a handful of things missing from BOF that we hope to see in future releases.
- Currently, there is no way to automatically distribute your Business Objects to client applications. If you create business objects, you must install the necessary JARs into the Classpath on every client machine that will use it. You will also need to register the business objects with the DBOR on every machine. This can be done with a custom installation program, but it does not happen automatically.
- It is unclear how the standard Documentum client applications will behave when your Business Objects throw exceptions or return error messages. For example, if you override the
save()method to do some custom validation, how will you notify the user that their attributes did not meet the validation criteria? You can throw an exception, but will the Desktop Client display it in a friendly error message?
